tfPop3UserGetMessageUid

Table of Contents >> Optional Protocols >> POP3

#include <trsocket.h>

char * tfPop3UserGetMessageUid	(
	ttPop3ClientHandle pop3Handle,
	int messageNumber,
	ttPop3CBGetUidFuncPtr getUidCBFuncPtr,
	int * errorCodePtr
	);

Function Description

This function retrieves the UID for the given messageNumber.

Parameters

• pop3Handle

  This is set to the user POP3 handle.

• messageNumber

  This is set to the message number from which to retrieve the UID.

• getUidCBFuncPtr

  When using non-blocking mode, this should be set to a pointer to the callback function used to retrieve the UID from the server. This argument is of type ttPop3CBGetUidFunc.

• errorCodePtr

  This contains the resultant error code.

Returns

• TM_EINVAL

  This indicates failure. The kernel found invalid arguments in the call. This can also indicate that the connection is not finished.

• TM_EINPROGRESS

  This indicates that the operation has not finished (non-blocking mode only). Call tfPop3UserExecute() until it returns a value other than TM_EINPROGRESS to detect completion.

• TM_ENOERROR

  This indicates success. The returned UID is valid for the given messageNumber.

• Other values

  Other error values indicate various forms of failure when attempting to send or receive UIDL commands.

Usage

Use this function to retrieve the UID for the given messageNumber. The returned pointer remains valid until one of the following occurs:

• tfPop3UserGetMessageUid() is called with a different message number
  
• tfPop3UserDisconnect() is called
  
• tfPop3FreeSession() is called
  

If UID caching is enabled, the cache is first checked for the appropriate UID. If the UID is not found, a UIDL command is sent to the server.

Non-blocking mode

If the UID is not already in the cache, this function returns 0 with the errorCodePtr content set to TM_EINPROGRESS. To continually check for completion, call tfPop3UserExecute() until it returns a value other than TM_EINPROGRESS. At that point, use getUidCBFuncPtr to retrieve the resultant value.

Table of Contents >> Optional Protocols >> POP3