tfPop3UserGetMessageSize

Table of Contents >> Optional Protocols >> POP3

#include <trsocket.h>

int tfPop3UserGetMessageSize	(
	ttPop3ClientHandle pop3Handle,
	int messageNumber,
	ttPop3CBGetSizeFuncPtr getSizeCBFuncPtr,
	int * errorCodePtr
	);

Function Description

This function is used to get the message size for a given message number. First, the cache list will be checked to see if this message size has been retrieved previously. If the message size is found, this function will return it immediately. Otherwise, a LIST command is sent to the POP3 server. For blocking mode, this function will block until a reply is received and the message size is returned. For non-blocking mode, a messageSize of -1 will be returned and 'errorCodePtr' will be set to TM_EINPROGRESS, to indicate that the query is currently underway. The user should continue calling tfPop3UserExecute() until it returns a value other than TM_EINPROGRESS.

Upon receiving a reply to the LIST command, the callback function will be triggered.

Most often, regardless of the blocking mode, the message size will be in the cache from when the connection was established and this function will return immediately. To set how many message sizes can be cached, see tfPop3SetSessionOption() and the option TM_POP3_OPTNAME_CACHEMESSAGE.

Parameters

• pop3Handle

  The POP3 session handle.

• messageNumber

  The message number to get the size of.

• getSizeCBFuncPtr

  The call-back function to call to inform the user of the message size.

• errorCodePtr

  A pointer to the errorCode.

Returns

• -1

  If 'errorCodePtr' is set to TM_EINPROGRESS then the session is operating in non-blocking mode and a query is underway. The user should continue calling tfPop3UserExecute() until it returns a value other than TM_EINPROGRESS. If the 'errorCodePtr' is not set to TM_EINPROGRESS, then there was an error and this call failed.

• (Other)

  The number of bytes for all of the messages currently in the mailbox.

Example Code

 
int byteOfM;
 
int myGetSizeCB (int msgNum, int msgSize)
{
    byteOfM = msgSize;
    return 0;
}
 
 
main()
{
    ...
    pop3Handle = tfPop3NewSession(...);
    ...
    tfPop3UserConnect(...);
    ...
    byteOfM = tfPop3UserGetMessageSize(pop3Handle,
                                       1,
                                       myGetSizeCB,
                                       &errorCode);
    if((byteOfM == -1) && (errorCode == TM_EINPROGRESS))
    {
        while(errorCode == TM_EINPROGRESS)
        {
            errorCode = tfPop3UserExecute(pop3Handle);
        }
    }
    assert(errorCode == TM_ENOERROR && byteOfM > 0);
/* Here, byteOfM should contain the value of message size of message #1 */
}
 

Table of Contents >> Optional Protocols >> POP3