POP3

Jump to: navigation, search

Table of Contents >> Optional Protocols


Structures

ttPop3ClientHandle

ttPop3ClientHandle is a void pointer to a POP3 structure. The user can only use the ttPop3ClientHandle to talk with the kernel.


ttPop3CBFuncPtr

int userCbFunc (
unsigned char replyType,
char status,
ttUserGenericUnion u1,
ttUserGenericUnion u2
);


Function Description

ttPop3CBFuncPtr is a user call back function when open a POP3 connection. It catches all possible replies from the POP3 server.


Parameters

  • replyType
    The type of the reply from the POP3 server, such as a reply from a USER command or a PASS command, etc. Valid values are listed in the table below.
  • status
    The status of the server reply, such as '+OK', '-ERR' or a continued line. Valid values are:
  • TM_POP3_REPLY_STATUS_OK: "+OK"
  • TM_POP3_REPLY_STATUS_ERR: "-ERR"
  • TM_POP3_REPLY_STATUS_CONT: TCP continued data. This applies only if the server sends the reply in scattered buffers.
  • u1
    A pointer to the reply data.
  • u2
    The length of the reply data.


Possible Values for 'replyType'

Name Value
TM_POP3_REPLY_HELLO 0
TM_POP3_REPLY_USER 1
TM_POP3_REPLY_PASS 2
TM_POP3_REPLY_APOP 3
TM_POP3_REPLY_STAT 4
TM_POP3_REPLY_LIST 5
TM_POP3_REPLY_RETR 6
TM_POP3_REPLY_DELE 7
TM_POP3_REPLY_NOOP 8
TM_POP3_REPLY_RSET 9
TM_POP3_REPLY_TOP 10
TM_POP3_REPLY_UIDL 11
TM_POP3_REPLY_QUIT 12
TM_POP3_REPLY_INVALID 255


Example Usage

If the user wants to know what the server reply is when either USER or PASS commands are sent to the server, they may use code similar to this:

int myPop3CBFunc(unsigned char       replyType,
                 char                status,
                 ttUserGenericUnion  u1,
                 ttUserGenericUnion  u2)
{
    ttUser8BitPtr   dataPtr;
    int             length;
 
    dataPtr = u1.genVoidParmPtr;
    length = u2.gen32bitParm;
 
    dataPtr[length] = '\0';
 
    switch(replyType)
    {
    case TM_POP3_REPLY_USER:
    case TM_POP3_REPLY_PASS:
        if(status == TM_POP3_REPLY_STATUS_OK)
        {
            printf("SERVER replied with an OK message : %s\n", dataPtr);
        }
        else if(status == TM_POP3_REPLY_STATUS_ERR)
        {
            printf("SERVER replied with an ERR message: %s \n", dataPtr);
        }
        break;
      default:
/* The user does not care what the reply is for other commands sent to the server */
       break;
    }
    return TM_ENOERROR;
}

ttPop3CBGetSizeFuncPtr

int getSizeCbFunc (
int msgNumber,
int msgSize
);


Function Description

This call back function is used for notifying the user that the size of message 'msgNumber' is msgSize. In blocking mode, the message size is returned when tfPop3UserGetMessageSize() returns. However, in non-blocking mode, if the message size is not cached before, the user must wait for the reply from the POP3 server in order to obtain the message size.


Parameters

  • msgNumber
    The number of the message.
  • msgSize
    The size of the message.


Public APIs

Please notice that some of the public function calls have a prefix like tfPop3Userxxxx. In non-blocking mode, these functions may return TM_EINPROGRESS, in which case, the user should continue calling tfPop3UserExecute() until it returns a value other than TM_EINPROGRESS. In blocking mode, the user is not allowed to call tfPop3UserExecute().


Example Code

Blocking Mode Example

{
 
    ...
 
/* 3.1.1 tfPop3NewSession */
    blockMode = TM_BLOCKING_ON;
    pop3Handle = tfPop3NewSession((ttPop3CBFuncPtr)0,
                                  30, /* timeout seconds */
                                  40, /* maximum username + password length */
                                  blockMode,
                                  0);
 
    assert(pop3Handle != (void*)0);
 
/* 3.1.2 tfPop3Connect, for blocking mode, it should return TM_ENOERROR */
    errorCode = tfPop3UserConnect(pop3Handle
                                  &serverSockAddr,
                                  "user@domain.com",
                                  "mypassword");
    assert(errorCode == TM_ENOERROR);
 
/* 3.1.3 get the total message numebr */
    totalM = tfPop3GetTotalMsgNumber(pop3Handle);
 
/* 3.1.4 get the total message bytes */
    totalB = tfPop3GetTotalMsgSize(pop3Handle);
 
    printf("TotalM=%d, totalB = %d\n", totalM, totalB);
 
/* 3.1.5 try to get message size */
    for(i=1; i<totalM; i++)
    {
 /* for blocking mode, we don't need a call-back function */
        byteOfM = tfPop3UserGetMessageSize(pop3Handle,
                                           i,
                                           (ttPop3CBGetSizeFuncPtr)0,
                                           &errorCode);
        printf("Length of MSG#%d is %d\n", i, byteOfM);
    }
 
/*
 * 3.1.6 try to retrieve messages #1 using buffer whose length is 100.
 * Remember that the messageSize of message#1 may be much bigger than 100.
 */
    recvLength = -1;
    errorCode = TM_ENOERROR;
    while(recvLength != 0 && errorCode == TM_ENOERROR)
    {
        recvLength = tfPop3GetMessage(pop3Handle,
                                      1,
                                      buffer1,
                                      100,
                                      &errorCode);
        if(recvLength > 0)
        {
/*
 * process the message data in buffer1, it has recvLength bytes of
 * message data. We will keep receiving until we get all the message
 * data
 */
        }
    }
/* 3.1.7 delete message #1 */
       tfPop3UserDeleteMessage(pop3Handle, 1);
 
/* 3.1.8 disconnect the session*/
       tfPop3UserDisconnect(pop3Handle);
 
/* 3.1.9  freee the session*/
       tfPop3FreeSession(pop3Handle);
 
    ...
}

Non-blocking Mode Example

int byteOfM;
 
int myGetSizeCB(int msgNum,int msgSize)
{
    byteOfM = msgSize;
    return 0;
}
 
main()
{
 
    ...
 
/* 3.2.1 tfPop3NewSession to get the handle buffer */
    blockMode = TM_BLOCKING_OFF;
    pop3Handle = tfPop3NewSession((ttPop3CBFuncPtr)0,
                                  30, /* timeout seconds */
                                  40, /* maximum username + password length */
                                  blockMode,
                                  0);
 
    assert(pop3Handle != (void*)0);
 
/* 3.2.2 make connection */
    errorCode = tfPop3UserConnect(pop3Handle
                                  &serverSockAddr,
                                  "user@domain.com",
                                  "mypassword");
    while(errorCode == TM_EINPROGRESS)
    {
        errorCode = tfPop3UserExecute(pop3Handle);
    }
    assert(errorCode == TM_ENOERROR); /* make sure no error happens */
 
/*
 * 3.2.3 get the total message number.
 * You don't need to call tfPop3UserExecute to finish this call. When we
 * initialized the connection, we retrieved this information and stored it.
 */
    totalM = tfPop3GetTotalMsgNumber(pop3Handle);
 
/* 3.2.4 get the total message bytes */
    totalB = tfPop3GetTotalMsgSize(pop3Handle);
 
    printf("TotalM=%d, totalB = %d\n", totalM, totalB);
 
/* 3.2.5 try to get message size */
    for(i=1; i<totalM; i++)
    {
        byteOfM = tfPop3UserGetMessageSize(pop3Handle,
                                           i,
                                           myGetSizeCB,
                                           &errorCode);
        if((byteOfM == -1) && (errorCode == TM_EINPROGRESS))
        {
            while(errorCode == TM_EINPROGRESS)
            {
            errorCode = tfPop3UserExecute(pop3Handle);
            }
        }
 
/*
 * Upon reaching here, we should have the byteOfM.
 * Make sure no errors have occured.
 */
        assert(errorCode == TM_ENOERROR && byteOfM > 0);
 
        printf("Length of MSG#%d is %d\n", i, byteOfM);
    }
 
/*
 * 3.2.6 try to retrieve messages #1 using buffer whose length is 100.
 * Remember that the messageSize of message#1 may be much bigger than 100.
 */
    recvLength = -1;
    errorCode = TM_ENOERROR;
    while(recvLength != 0 && errorCode == TM_ENOERROR)
    {
        recvLength = tfPop3GetMessage(pop3Handle,
                                      1,
                                      buffer1,
                                      100,
                                      &errorCode);
        if(recvLength > 0)
        {
/*
 * process the message data in buffer1, it has recvLength bytes of
 * message data. We will keep receiving until we get all the message
 * data
 */
        }
    }
 
/* 3.2.7 delete message #1 */
    errorCode = tfPop3UserDeleteMessage(pop3Handle, 1);
    while(errorCode == TM_EINPROGRESS)
    {
        errorCode = tfPop3UserExecute(pop3Handle);
    }
    assert(errorCode == TM_ENOERROR); /* make sure no error happens */
 
/*
 * 3.2.8 disconnect the session.
 * You don't need to call tfPop3UserExecute for a disconnection command
 */
    tfPop3UserDisconnect(pop3Handle);
 
/* 3.2.9 free the session */
    tfPop3FreeSession(pop3Handle);
 
    ...
}


Table of Contents >> Optional Protocols