SFXPOP3

Class for processing the POP3 protocol.

#include <SFXPOP3.h.hpp>

class SFXPOP3;

SFMTYPEDEFCLASS(SFXPOP3)

Collaboration diagram

Procedure to receive a POP3 mail

Create the instance of the SFXPOP3 class. At this time, resources for receiving a POP3 mail are not allocated.
To perform the initialization for receiving a POP3 mail, call the SFXPOP3::Open function. And then to connect to the POP3 server, call the SFXPOP3::Connect function. In the SFXPOP3::Connect function, register a callback function which will be notified of the completion of receiving a POP3 mail.
A POP3 mail can be received when the connection to the POP3 server is established.
Send a POP3 command to the POP3 server using the function such as SFXPOP3::SendCommand.
The callback function registered using the SFXPOP3::Connect function will be notified when the response to a POP3 command from the POP3 server is received.
When finish receiving a POP3 mail, call the SFXPOP3::SendQuitCommand function to send the QUIT command to the POP3 server. And finally after confirming the response from the POP3 server, call the SFXPOP3::Close function to terminate the connection to the POP3 server.

Description

	Detailed information on the POP3 protocol
	POP3 specification: RFC1939 (Post Office Protocol - Version 3)

Reference

SFXSMTP | SFXSMTPSender | SFXPOP3Receiver | Mail Receiving

Member

Constructor/Destructor
SFXPOP3( `Void` ) Constructor of SFXPOP3 class,
~SFXPOP3( `Void` ) Destructor of SFXPOP3 class.

Public Functions
`Void`	Cancel( `Void` ) Cancel receiving a POP3 mail.
`Void`	Close( `Void` ) Close the connection to the POP3 server.
`SFCError`	Connect( `SFXSocketAddressConstRef` address , `CallbackSPP` spp , `VoidPtr` reference ) Connect to the POP3 server.
`SFCError`	GetListResponse( `NumberSizeRecHandle` recHandle , `SInt32Ptr` recCount ) GetListResponse( `NumberSizeRecPtr` rec ) Get the response of LIST command.
`SFCError`	GetLocalAddress( `SFXSocketAddressPtr` result ) Get the local IP address and port number.
`SFCError`	GetRemoteAddress( `SFXSocketAddressPtr` result ) Get the remote IP address and port number.
`VoidConstPtr`	GetResponseBuffer( `UInt32Ptr` size = null ) Get the response buffer.
`SFXAnsiString`	GetResponseText( `Void` ) Get the response text.
`SFCError`	GetResponseText( `SFXAnsiStringPtr` result ) Get the response text.
`SFCError`	GetRetrResponse( `ACharConstHandle` response ) GetRetrResponse( `SFXAnsiStringPtr` response ) Get the response to the RETR command.
`Bool`	GetSSLMode( `Void` ) Get the SSL connection mode.
`SFCError`	GetStatResponse( `UInt32Ptr` count = null , `UInt32Ptr` size = null ) Get the response of STAT command.
`SFCError`	GetTopResponse( `ACharConstHandle` response ) GetTopResponse( `SFXAnsiStringPtr` response ) Get the response to the TOP command.
`UInt32`	GetTrustMode( `Void` ) Get the SSL trust mode.
`SFCError`	GetUidlResponse( `NumberUidlRecHandle` recHandle , `SInt32Ptr` recCount ) GetUidlResponse( `NumberUidlRecPtr` rec ) Get the response to the UIDL command.
`Bool`	IsResponseErr( `Void` ) Check whether the response status of the latest POP3 command is "-ERR" or not.
`Bool`	IsResponseOk( `Void` ) Check whether the response status of the latest POP3 command is "+OK" or not.
`SFCError`	Open( `Void` ) Perform the initialization for connecting to the POP3 server.
`SFCError`	SendApopCommand( `SFXAnsiStringConstRef` user , `SFXAnsiStringConstRef` password , `SFXAnsiStringConstRef` challenge ) Send the APOP command.
`SFCError`	SendCommand( `ACharConstPtr` command , `UInt32` size , `Bool` multiline ) SendCommand( `SFXAnsiStringConstRef` command , `Bool` multiline ) Send the POP3 command.
`SFCError`	SendDeleCommand( `SInt32` number ) Send the DELE command.
`SFCError`	SendListCommand( `Void` ) SendListCommand( `SInt32` number ) Send the LIST command.
`SFCError`	SendNoopCommand( `Void` ) Send the NOOP command.
`SFCError`	SendPassCommand( `SFXAnsiStringConstRef` password ) Send the PASS command.
`SFCError`	SendQuitCommand( `Void` ) Send the QUIT command.
`SFCError`	SendRetrCommand( `SInt32` number ) Send the RETR command.
`SFCError`	SendRsetCommand( `Void` ) Send the RSET command.
`SFCError`	SendStatCommand( `Void` ) Send the STAT command.
`SFCError`	SendTopCommand( `SInt32` number , `UInt32` lines ) Send the TOP command.
`SFCError`	SendUidlCommand( `Void` ) SendUidlCommand( `SInt32` number ) Send the UIDL command.
`SFCError`	SendUserCommand( `SFXAnsiStringConstRef` user ) Send the USER command.
`Void`	SetSSLMode( `Bool` isSSL ) Set the SSL connection mode.
`SFCError`	SetTrustMode( `UInt32` sslTrustMode ) Set the SSL trust mode.

Types
CallbackSPP Prototype of callback function.
NumberSizeRec Structure to store the result of the SFXPOP3::GetListResponse function.
NumberUidlRec Structure to store the result of the SFXPOP3::GetUidlResponse function.

SFXPOP3::SFXPOP3

Constructor of SFXPOP3 class,

[ public, explicit ]
SFXPOP3(Void);

Description

Resources for receiving a POP3 mail will not be allocated when the instance of the SFXPOP3 class is created. Those resources will be allocated after calling the SFXPOP3::Open function.

Reference

SFXPOP3::Open

SFXPOP3::~SFXPOP3

Destructor of SFXPOP3 class.

[ public, virtual ]
~SFXPOP3(Void);

Description

The SFXPOP3::Close function needs to be called before destroying the instance of the SFXPOP3 class.

Reference

SFXPOP3::Close

SFXPOP3::Cancel

Cancel receiving a POP3 mail.

[ public ]
Void Cancel(Void);

Description

The SFXTCPSocket::Cancel function is called internally in this function.

Reference

SFXPOP3::Close

SFXPOP3::Close

Close the connection to the POP3 server.

[ public ]
Void Close(Void);

Description

Resources for receiving a POP3 mail will be released. If during processing, it will be canceled.

	How to terminate the connection to the POP3 server
	After confirming the response to the QUIT command sent by the `SFXPOP3::SendQuitCommand` function from the POP3 server, terminate the connection to the POP3 server using the SFXPOP3::Close function

Reference

SFXPOP3::SendQuitCommand | SFXPOP3::Connect

SFXPOP3::Connect

Connect to the POP3 server.

[ public ]
SFCError Connect(
    SFXSocketAddressConstRef address   // IP address and port number of the POP3 server 
    CallbackSPP spp                    // callback function
    VoidPtr reference                  // argument for the callback
);

Argument

endpoint: Specify the POP3 server IP address and port number.

Return value

Success : SFERR_NO_ERROR
If socket is not opened or it has already been connected (including connection processing): SFERR_INVALID_STATE
If IP address and port number of the POP3 server have not been set : SFERR_INVALID_STATE
If failed to create the SFBNetMgr instance : SFERR_FAILED
If insufficient memory : SFERR_NO_MEMORY
For other network errors: get error value by SFBSocket::GetLastError function.

Description

	Error when connecting to the POP3 server
	An error occurred when connecting to the POP3 server is notified to the callback function.

Reference

SFXPOP3::Open | SFXPOP3::Close

SFXPOP3::GetListResponse

Get the response of LIST command.

[ public, const ]
SFCError GetListResponse(
    NumberSizeRecHandle recHandle   // list of mail message numbers
    SInt32Ptr recCount              // number of items in mail list
);

[ public, const ]
SFCError GetListResponse(
    NumberSizeRecPtr rec   // mail message number
);

Argument

recHandle: Specify a handle to store the pointer to the array of the SFXPOP3::NumberSizeRec structure of a mail message number and its size obtained from the POP3 server. This array must be released by the caller using the delete[] operator.
recCount: Specify a pointer to the variable to store the size of the recHandle array obtained from the POP3 server.
rec: Specify a pointer to the variable to store the SFXPOP3::NumberSizeRec structure of a mail message number and its size obtained from the POP3 server.

Return value

Success : SFERR_NO_ERROR
If invalid argument : SFERR_INVALID_PARAM
If connection has not been established, or the status of response to the last POP3 command is not "+OK" : SFERR_INVALID_STATE
If failed to parse the response : SFERR_INVALID_FORMAT
If insufficient memory : SFERR_NO_MEMORY

Description

The LIST command is the command to get the size of mail messages from the POP3 server.

The usage of the SFXPOP3::GetListResponse function differs depending on the number of arguments of the SFXPOP3::SendListCommand function.

When the SFXPOP3::SendListCommand function is called with no argument: The "recHandle" and "recCount" arguments need to be specified. All mail message numbers and their sizes will be obtained.
When the SFXPOP3::SendListCommand function is called with one argument: Only the "rec" argument needs to be specified. The size of mail message which number is specified by the SFXPOP3::SendListCommand function will be obtained.

The SFXPOP3::GetListResponse function will fail and return SFERR_INVALID_FORMAT if the arguments are not properly set for the corresponding arguments of the SFXPOP3::SendListCommand function called. The return value other than SFERR_NO_ERROR means that invalid values may be set to the arguments.

Reference

SFXPOP3::SendListCommand | SFXPOP3::NumberSizeRec

SFXPOP3::GetLocalAddress

Get the local IP address and port number.

[ public, const ]
SFCError GetLocalAddress(
    SFXSocketAddressPtr result   //  pointer to the variable to store the local IP address and port number
);

Return value

Success : SFERR_NO_ERROR
If connection has not been established : SFERR_INVALID_STATE
If argument is null : SFERR_INVALID_PARAM
For other network errors: get error value by SFBSocket::GetLastError function.

Description

	Local IP address may be changed
	There is a possibility that the local IP address may be changed after connecting to the POP3 server.

Reference

SFXInetAddress::LocalInetAddress | SFXTCPSocket::GetLocalAddress

SFXPOP3::GetRemoteAddress

Get the remote IP address and port number.

[ public, const ]
SFCError GetRemoteAddress(
    SFXSocketAddressPtr result   // pointer to the variable to store the remote IP address and port number
);

Return value

Success : SFERR_NO_ERROR
If connection has not been established : SFERR_INVALID_STATE
If argument is null : SFERR_INVALID_PARAM

Description

	Remote IP address may be changed
	There is a possibility that the remote IP address may be changed after connecting to the POP3 server.

Reference

SFXTCPSocket::GetRemoteAddress

SFXPOP3::GetResponseBuffer

Get the response buffer.

[ public, const ]
VoidConstPtr GetResponseBuffer(
    UInt32Ptr size = null   // buffer size
);

Argument

size: Specify a pointer to the variable to store the size of the response buffer obtained from the POP3 server. Specify null if unnecessary.

Description

At the head of the buffer, there is a response("+OK" or "-ERR" ) from the POP3 server and an additional message.

If the response has only one line, "\r\n" is not included in the buffer.

If the response has more than one line, ".\r\n" of the last line and the period at the begining of lines are not included in the buffer.

The obtained buffer is valid as long as the status does not change. The buffer will be invalid if the state is changed by sending a command or calling the SFXPOP3::Close function.

Reference

SFXPOP3::GetResponseText

SFXPOP3::GetResponseText

Get the response text.

[ public, const ]
SFXAnsiString GetResponseText(Void);

[ public, const ]
SFCError GetResponseText(
    SFXAnsiStringPtr result   // pointer to the variable to store the response text from the POP3 server
);

Argument

result: Specify a pointer to the variable to store the response text obtained from the SMTP server.

Return value

Success : SFERR_NO_ERROR
If connection has not been established : SFERR_INVALID_STATE
If failed to receiving a response message : SFERR_FAILED
If insufficient memory : SFERR_NO_MEMORY

Description

When the response message has only one line, "\r\n" is not included in the response text.

If the response message has more than one line, ".\r\n" of the last line and the period at the begining of lines are not included in the response text.

	About response text
	Response text is the partial response message, which is the text removed the status string("+OK" or "-ERR" ) at the beginning and succeeding whitespace from the response message from the POP3 server.

Reference

SFXPOP3::GetResponseBuffer

SFXPOP3::GetRetrResponse

Get the response to the RETR command.

[ public, const ]
SFCError GetRetrResponse(
    ACharConstHandle response   // handle to store the pointer to the response to the RETR command
);

[ public, const ]
SFCError GetRetrResponse(
    SFXAnsiStringPtr response   // pointer to the response to the RETR command
);

Argument

response: Specify a handle to store the pointer to the response to the RETR command or a pointer to the response to the RETR command.

Return value

Success : SFERR_NO_ERROR
If invalid argument : SFERR_INVALID_PARAM
If connection has not been established, or the status immediately before POP3 command is not "+OK" : SFERR_INVALID_STATE
If insufficient memory : SFERR_NO_MEMORY

Description

The RETR command is the command to get the mail message.

If the response has only one line, "\r\n" is not included in the response.

If the response has more than one line, the ".\r\n" of the last line and the period at the begining of lines is not included in the response.

	Note
	The value of the "response" argument of the ACharConstHandle type is the pointer to the buffer of the internal class of the SFXPOP3 class. This buffer must not be released by the caller.

Reference

SFXPOP3::SendRetrCommand

SFXPOP3::GetSSLMode

Get the SSL connection mode.

[ public, const ]
Bool GetSSLMode(Void);

Return value

If valid : true
Otherwise : false

Reference

SFXPOP3::SetSSLMode

SFXPOP3::GetStatResponse

Get the response of STAT command.

[ public, const ]
SFCError GetStatResponse(
    UInt32Ptr count = null   // number of mail messages
    UInt32Ptr size = null    // size of all messages
);

Argument

count: Specify a pointer to the variable to store the number of mail messages. Specify null if unnecessary.
size: Specify a pointer to the variable to store the total size of all mail messages. Specify null if unnecessary.

Return value

Success : SFERR_NO_ERROR
If connection has not been established, or the status immediately before POP3 command is not "+OK" : SFERR_INVALID_STATE
If failed to parse the response : SFERR_INVALID_FORMAT

Description

The STAT command is the command to get the number and total size of mail messages.

Reference

SFXPOP3::SendStatCommand

SFXPOP3::GetTopResponse

Get the response to the TOP command.

[ public, const ]
SFCError GetTopResponse(
    ACharConstHandle response   // pointer to the response to the TOP command(handle)
);

[ public, const ]
SFCError GetTopResponse(
    SFXAnsiStringPtr response   //  pointer to the response to the TOP command
);

Argument

response: Specify a pointer to the response to the TOP command.

Return value

Success : SFERR_NO_ERROR
If invalid argument : SFERR_INVALID_PARAM
If connection has not been established, or the status immediately before POP3 command is not "+OK" : SFERR_INVALID_STATE
If insufficient memory : SFERR_NO_MEMORY

Description

The TOP command is the command to get the header and body of mail message.

Reference

SFXPOP3::SendTopCommand

SFXPOP3::GetTrustMode

Get the SSL trust mode.

[ public, const ]
UInt32 GetTrustMode(Void);

Description

The SSL trust mode can be one of the following values.

SSL_TRUST_MODE_FAIL
SSL_TRUST_MODE_CHECK
SSL_TRUST_MODE_IGNORE
SSL_TRUST_MODE_ALWAYS

	Note
	Detailed information: ISSL_NegotiateV in the BREW API Reference

Reference

BREW API ISSL_NegotiateV | SFXPOP3::SetTrustMode

SFXPOP3::GetUidlResponse

Get the response to the UIDL command.

[ public, const ]
SFCError GetUidlResponse(
    NumberUidlRecHandle recHandle   // handle to store the pointer to the array of message number and UIDL
    SInt32Ptr recCount              // number of items in the list
);

[ public, const ]
SFCError GetUidlResponse(
    NumberUidlRecPtr rec   // message number and UIDL
);

Argument

recHandle: Specify a handle to store the pointer to the array of SFXPOP3::NumberUidlRec structures of mail message number and UIDL. The "recHandle" array needs to be released by the caller using the delete[] operator.
recCount: Specify a pointer to the variable to store the number of items in recHandle list.
rec: Specify a pointer to the SFXPOP3::NumberUidlRec structure of mail message number and UIDL.

Return value

Success : SFERR_NO_ERROR
If invalid argument : SFERR_INVALID_PARAM
If connection has not been established, or the status immediately before POP3 command is not "+OK" : SFERR_INVALID_STATE
If failed to parse the response to the UIDL command : SFERR_INVALID_FORMAT
If insufficient memory : SFERR_NO_MEMORY

Description

The UIDL command is the command to get the UIDL of mail message.

The usage of this function differs depending on the number of arguments of SFXPOP3::SendUidlCommand function.

When the SFXPOP3::SendUidlCommand function is called with no argument: The "recHandle" and "recCount" arguments need to be specified. All mail message numbers and UIDLs will be obtained.
When the SFXPOP3::SendUidlCommand function is called with one argument: Only the "rec" argument needs to be specified. The UIDL of mail message which number is specified by the SFXPOP3::SendUidlCommand function will be obtained.

The SFXPOP3::GetUidlResponse function will fail and return SFERR_INVALID_FORMAT if the arguments are not properly set for the corresponding arguments of the SFXPOP3::SendUidlCommand function. The return value other than SFERR_NO_ERROR means that invalid values may be set to the arguments.

Reference

SFXPOP3::SendUidlCommand | SFXPOP3::NumberUidlRec

SFXPOP3::IsResponseErr

Check whether the response status of the latest POP3 command is "-ERR" or not.

[ public, const ]
Bool IsResponseErr(Void);

Return value

If "-ERR" : true
Otherwise : false

Reference

SFXPOP3::IsResponseOk

SFXPOP3::IsResponseOk

Check whether the response status of the latest POP3 command is "+OK" or not.

[ public, const ]
Bool IsResponseOk(Void);

Return value

If "+OK" : true
Otherwise : false

Reference

SFXPOP3::IsResponseErr

SFXPOP3::Open

Perform the initialization for connecting to the POP3 server.

[ public ]
SFCError Open(Void);

Return value

Success : SFERR_NO_ERROR
If socket has already been opened : SFERR_INVALID_STATE
If failed to create the instance of the SFBNetMgr or SFBSSL class : SFERR_FAILED
If failed : AEE_NET_ERROR

Description

SFXTCPSocket class's SFXTCPSocket::Open function is called internally.

Reference

SFXPOP3::Close

SFXPOP3::SendApopCommand

Send the APOP command.

[ public ]
SFCError SendApopCommand(
    SFXAnsiStringConstRef user        // username
    SFXAnsiStringConstRef password    // password
    SFXAnsiStringConstRef challenge   // challenge code
);

Argument

user: Username.
password: Password.
challenge: Challenge code for the APOP authentication. The string enclosed by < > included in the response to the EHLO command is passed.

Return value

Success : SFERR_NO_ERROR
If invalid argument : SFERR_INVALID_PARAM
If connection has not been established : SFERR_INVALID_STATE
If insufficient memory : SFERR_NO_MEMORY
If failed : SFERR_FAILED
For other errors: error values are defined in AEEError.h

Description

The APOP command is for the APOP authentication.

Call the SFXPOP3::SendApopCommand function immediately after the connection to the POP3 server is established by the SFXPOP3::Connect function.

Method to get the communication error and the command error

	Method to get the communication error and the command error
Only the error about the internal processing of this function will be returned as return value. The communication error is notified to the callback function registered using the `SFXPOP3::Connect` function. To check whether the command succeeded or not, use the `SFXPOP3::IsResponseOk` or `SFXPOP3::IsResponseErr` function.

Only the error about the internal processing of this function will be returned as return value.

The communication error is notified to the callback function registered using the SFXPOP3::Connect function.

To check whether the command succeeded or not, use the SFXPOP3::IsResponseOk or SFXPOP3::IsResponseErr function.

Reference

SFXPOP3::IsResponseOk | SFXPOP3::IsResponseErr | SFXPOP3::Connect

SFXPOP3::SendCommand

Send the POP3 command.

[ public ]
SFCError SendCommand(
    ACharConstPtr command   // POP3 command
    UInt32 size             // size of the POP3 command
    Bool multiline          // whether a specified POP3 command supports the multi-line response or not
);

[ public ]
SFCError SendCommand(
    SFXAnsiStringConstRef command   // POP3 command
    Bool multiline                  // whether a specified POP3 command supports the multi-line response or not
);

Return value

Success : SFERR_NO_ERROR
If invalid argument : SFERR_INVALID_PARAM
If connection has not been established : SFERR_INVALID_STATE
If failed : SFERR_FAILED
For other errors: error values are defined in AEEError.h

Description

"\r\n" needs to be added at the end of the POP3 command. Whether a specified POP3 command supports the multi-line response or not is specified by the "multiline" argument.

Method to get the communication error and the command error

	Method to get the communication error and the command error
Only the error about the internal processing of this function will be returned as return value. The communication error is notified to the callback function registered using the `SFXPOP3::Connect` function. To check whether the command succeeded or not, use the `SFXPOP3::IsResponseOk` or `SFXPOP3::IsResponseErr` function.

Only the error about the internal processing of this function will be returned as return value.

The communication error is notified to the callback function registered using the SFXPOP3::Connect function.

To check whether the command succeeded or not, use the SFXPOP3::IsResponseOk or SFXPOP3::IsResponseErr function.

Reference

SFXPOP3::SendDeleCommand

Send the DELE command.

[ public ]
SFCError SendDeleCommand(
    SInt32 number   // message number
);

Argument

number: Specify a mail message number to be deleted.

Return value

Success : SFERR_NO_ERROR
If invalid argument : SFERR_INVALID_PARAM
If connection has not been established : SFERR_INVALID_STATE
If failed : SFERR_FAILED
For other errors: error values are defined in AEEError.h

Description

The DELE command is the command to delete a mail message.

Method to get the communication error and the command error

	Method to get the communication error and the command error
Only the error about the internal processing of this function will be returned as return value. The communication error is notified to the callback function registered using the `SFXPOP3::Connect` function. To check whether the command succeeded or not, use the `SFXPOP3::IsResponseOk` or `SFXPOP3::IsResponseErr` function.

Only the error about the internal processing of this function will be returned as return value.

The communication error is notified to the callback function registered using the SFXPOP3::Connect function.

To check whether the command succeeded or not, use the SFXPOP3::IsResponseOk or SFXPOP3::IsResponseErr function.

Reference

SFXPOP3::IsResponseOk | SFXPOP3::IsResponseErr | SFXPOP3::Connect

SFXPOP3::SendListCommand

Send the LIST command.

[ public ]
SFCError SendListCommand(Void);

[ public ]
SFCError SendListCommand(
    SInt32 number   // number of the size of mail message to be obtained
);

Argument

number: Specify a number of the size of mail message to be obtained. It should be not less than 1.

Return value

Success : SFERR_NO_ERROR
If the "number" argument is less than 1 : SFERR_INVALID_PARAM
If connection has not been established : SFERR_INVALID_STATE
If failed : SFERR_FAILED
For other errors: error values are defined in AEEError.h

Description

The LIST command is the command to get the size of mail messages.

To get the size of all the mail messages, call the SFXPOP3::SendListCommand function with no argument . To get the size of a specific mail message, specify the mail message number to the argument. The result of the LIST command is obtained using the SFXPOP3::GetListResponse function.

Method to get the communication error and the command error

	Method to get the communication error and the command error
Only the error about the internal processing of this function will be returned as return value. The communication error is notified to the callback function registered using the `SFXPOP3::Connect` function. To check whether the command succeeded or not, use the `SFXPOP3::IsResponseOk` or `SFXPOP3::IsResponseErr` function.

Only the error about the internal processing of this function will be returned as return value.

The communication error is notified to the callback function registered using the SFXPOP3::Connect function.

To check whether the command succeeded or not, use the SFXPOP3::IsResponseOk or SFXPOP3::IsResponseErr function.

Reference

SFXPOP3::GetListResponse | SFXPOP3::IsResponseOk | SFXPOP3::IsResponseErr | SFXPOP3::Connect

SFXPOP3::SendNoopCommand

Send the NOOP command.

[ public ]
SFCError SendNoopCommand(Void);

Return value

Success : SFERR_NO_ERROR
If connection has not been established : SFERR_INVALID_STATE
If failed : SFERR_FAILED
For other errors: error values are defined in AEEError.h

Description

The NOOP command is the command to check the connection to the POP3 server.

When the POP3 server receives the NOOP command, it returns only the response message.

Method to get the communication error and the command error

	Method to get the communication error and the command error
Only the error about the internal processing of this function will be returned as return value. The communication error is notified to the callback function registered using the `SFXPOP3::Connect` function. To check whether the command succeeded or not, use the `SFXPOP3::IsResponseOk` or `SFXPOP3::IsResponseErr` function.

Only the error about the internal processing of this function will be returned as return value.

The communication error is notified to the callback function registered using the SFXPOP3::Connect function.

To check whether the command succeeded or not, use the SFXPOP3::IsResponseOk or SFXPOP3::IsResponseErr function.

Reference

SFXPOP3::IsResponseOk | SFXPOP3::IsResponseErr | SFXPOP3::Connect

SFXPOP3::SendPassCommand

Send the PASS command.

[ public ]
SFCError SendPassCommand(
    SFXAnsiStringConstRef password   // password
);

Argument

password: Specify a password.

Return value

Success : SFERR_NO_ERROR
If invalid argument : SFERR_INVALID_PARAM
If connection has not been established : SFERR_INVALID_STATE
If failed : SFERR_FAILED
For other errors: error values are defined in AEEError.h

Description

The PASS command is the command to set a password.

The SFXPOP3::SendPassCommand function is called immediately after sending a user name using the SFXPOP3::SendUserCommand function.

Method to get the communication error and the command error

	Method to get the communication error and the command error
Only the error about the internal processing of this function will be returned as return value. The communication error is notified to the callback function registered using the `SFXPOP3::Connect` function. To check whether the command succeeded or not, use the `SFXPOP3::IsResponseOk` or `SFXPOP3::IsResponseErr` function.

Only the error about the internal processing of this function will be returned as return value.

The communication error is notified to the callback function registered using the SFXPOP3::Connect function.

To check whether the command succeeded or not, use the SFXPOP3::IsResponseOk or SFXPOP3::IsResponseErr function.

Reference

SFXPOP3::IsResponseOk | SFXPOP3::IsResponseErr | SFXPOP3::Connect

SFXPOP3::SendQuitCommand

Send the QUIT command.

[ public ]
SFCError SendQuitCommand(Void);

Return value

Success : SFERR_NO_ERROR
If connection has not been established : SFERR_INVALID_STATE
If failed : SFERR_FAILED
For other errors: error values are defined in AEEError.h

Description

The QUIT command is the command to terminate the session of receiving a POP3 mail.

	How to terminate the connection to the POP3 server
	After confirming the response to the QUIT command sent by the SFXPOP3::SendQuitCommand function from the POP3 server, terminate the connection to the POP3 server using the `SFXPOP3::Close` function

Method to get the communication error and the command error

	Method to get the communication error and the command error
Only the error about the internal processing of this function will be returned as return value. The communication error is notified to the callback function registered using the `SFXPOP3::Connect` function. To check whether the command succeeded or not, use the `SFXPOP3::IsResponseOk` or `SFXPOP3::IsResponseErr` function.

Only the error about the internal processing of this function will be returned as return value.

The communication error is notified to the callback function registered using the SFXPOP3::Connect function.

To check whether the command succeeded or not, use the SFXPOP3::IsResponseOk or SFXPOP3::IsResponseErr function.

Reference

SFXPOP3::Close | SFXPOP3::IsResponseOk | SFXPOP3::IsResponseErr | SFXPOP3::Connect

SFXPOP3::SendRetrCommand

Send the RETR command.

[ public ]
SFCError SendRetrCommand(
    SInt32 number   // number of the mail message to be obtained
);

Argument

number: Specify the number of the mail message to be obtained. It should be not less than 1.

Return value

Success : SFERR_NO_ERROR
If the "number" argument is less than 1 : SFERR_INVALID_PARAM
If connection has not been established : SFERR_INVALID_STATE
If failed : SFERR_FAILED
For other errors: error values are defined in AEEError.h

Description

The RETR command is the command to get the mail message.

The result of the RETR command is obtained using the SFXPOP3::GetRetrResponse function.

Method to get the communication error and the command error

	Method to get the communication error and the command error
Only the error about the internal processing of this function will be returned as return value. The communication error is notified to the callback function registered using the `SFXPOP3::Connect` function. To check whether the command succeeded or not, use the `SFXPOP3::IsResponseOk` or `SFXPOP3::IsResponseErr` function.

Only the error about the internal processing of this function will be returned as return value.

The communication error is notified to the callback function registered using the SFXPOP3::Connect function.

To check whether the command succeeded or not, use the SFXPOP3::IsResponseOk or SFXPOP3::IsResponseErr function.

Reference

SFXPOP3::GetRetrResponse | SFXPOP3::IsResponseOk | SFXPOP3::IsResponseErr | SFXPOP3::Connect

SFXPOP3::SendRsetCommand

Send the RSET command.

[ public ]
SFCError SendRsetCommand(Void);

Return value

Success : SFERR_NO_ERROR
If connection has not been established : SFERR_INVALID_STATE
If failed : SFERR_FAILED
For other errors: error values are defined in AEEError.h

Description

The RSET command is the command to reset the session of receiving a POP3 mail.

The results of the SFXPOP3::SendUserCommand and SFXPOP3::SendPassCommand functions will be destroyed and connection to the POP3 server will be initialized.

Method to get the communication error and the command error

	Method to get the communication error and the command error
Only the error about the internal processing of this function will be returned as return value. The communication error is notified to the callback function registered using the `SFXPOP3::Connect` function. To check whether the command succeeded or not, use the `SFXPOP3::IsResponseOk` or `SFXPOP3::IsResponseErr` function.

Only the error about the internal processing of this function will be returned as return value.

The communication error is notified to the callback function registered using the SFXPOP3::Connect function.

To check whether the command succeeded or not, use the SFXPOP3::IsResponseOk or SFXPOP3::IsResponseErr function.

Reference

SFXPOP3::IsResponseOk | SFXPOP3::IsResponseErr | SFXPOP3::Connect

SFXPOP3::SendStatCommand

Send the STAT command.

[ public ]
SFCError SendStatCommand(Void);

Return value

Success : SFERR_NO_ERROR
If connection has not been established : SFERR_INVALID_STATE
If failed : SFERR_FAILED
For other errors: error values are defined in AEEError.h

Description

The STAT command is the command to get the number and total size of mail messages.

The result of the STAT command is obtained using the SFXPOP3::GetStatResponse function.

Method to get the communication error and the command error

	Method to get the communication error and the command error
Only the error about the internal processing of this function will be returned as return value. The communication error is notified to the callback function registered using the `SFXPOP3::Connect` function. To check whether the command succeeded or not, use the `SFXPOP3::IsResponseOk` or `SFXPOP3::IsResponseErr` function.

Only the error about the internal processing of this function will be returned as return value.

The communication error is notified to the callback function registered using the SFXPOP3::Connect function.

To check whether the command succeeded or not, use the SFXPOP3::IsResponseOk or SFXPOP3::IsResponseErr function.

Reference

SFXPOP3::GetStatResponse | SFXPOP3::IsResponseOk | SFXPOP3::IsResponseErr | SFXPOP3::Connect

SFXPOP3::SendTopCommand

Send the TOP command.

[ public ]
SFCError SendTopCommand(
    SInt32 number   // number of the mail message to be obtained
    UInt32 lines    // number of text lines of the mail message to be obtained
);

Argument

number: Specify the number of the mail message to be obtained. Should be an integer not less than 1.
lines: Specify the number of text lines of the mail message to be obtained. If 0 is specified, only the header will be obtained.

Return value

Success : SFERR_NO_ERROR
If the "number" argument is less than 1 or invalid argument : SFERR_INVALID_PARAM
If connection has not been established : SFERR_INVALID_STATE
If failed : SFERR_FAILED
For other errors: error values are defined in AEEError.h

Description

The TOP command is the command to get the header and body of the mail message.

The result of the TOP command is obtained using the SFXPOP3::GetTopResponse function.

Method to get the communication error and the command error

	Method to get the communication error and the command error
Only the error about the internal processing of this function will be returned as return value. The communication error is notified to the callback function registered using the `SFXPOP3::Connect` function. To check whether the command succeeded or not, use the `SFXPOP3::IsResponseOk` or `SFXPOP3::IsResponseErr` function.

Only the error about the internal processing of this function will be returned as return value.

The communication error is notified to the callback function registered using the SFXPOP3::Connect function.

To check whether the command succeeded or not, use the SFXPOP3::IsResponseOk or SFXPOP3::IsResponseErr function.

Reference

SFXPOP3::GetTopResponse | SFXPOP3::IsResponseOk | SFXPOP3::IsResponseErr | SFXPOP3::Connect

SFXPOP3::SendUidlCommand

Send the UIDL command.

[ public ]
SFCError SendUidlCommand(Void);

[ public ]
SFCError SendUidlCommand(
    SInt32 number   // number of the mail message to be obtained
);

Argument

number: Specify the number of the mail message to be obtained. Should be an integer not less than 1.

Return value

Success : SFERR_NO_ERROR
If the "number" argument is less than 1 : SFERR_INVALID_PARAM
If connection has not been established : SFERR_INVALID_STATE
If failed : SFERR_FAILED
For other errors: error values are defined in AEEError.h

Description

The UIDL command is the command to get the mail message's UIDL.

To get all the UIDLs of the mail messages, call the SFXPOP3::SendUidlCommand function with no argument. To get the UIDL of a specific mail message, specify the mail message number to the argument . The result of the UIDL command is obtanined using the SFXPOP3::GetUidlResponse function.

Method to get the communication error and the command error

	Method to get the communication error and the command error
Only the error about the internal processing of this function will be returned as return value. The communication error is notified to the callback function registered using the `SFXPOP3::Connect` function. To check whether the command succeeded or not, use the `SFXPOP3::IsResponseOk` or `SFXPOP3::IsResponseErr` function.

Only the error about the internal processing of this function will be returned as return value.

The communication error is notified to the callback function registered using the SFXPOP3::Connect function.

To check whether the command succeeded or not, use the SFXPOP3::IsResponseOk or SFXPOP3::IsResponseErr function.

Reference

SFXPOP3::GetUidlResponse | SFXPOP3::IsResponseOk | SFXPOP3::IsResponseErr | SFXPOP3::Connect

SFXPOP3::SendUserCommand

Send the USER command.

[ public ]
SFCError SendUserCommand(
    SFXAnsiStringConstRef user   // username
);

Argument

user: Specify a username.

Return value

Success : SFERR_NO_ERROR
If invalid argument : SFERR_INVALID_PARAM
If connection has not been established : SFERR_INVALID_STATE
If failed : SFERR_FAILED
For other errors: error values are defined in AEEError.h

Description

The USER command is the command to set a username.

The SFXPOP3::SendUserCommand function is called after the connection to the POP3 server is established by the SFXPOP3::Connect function.

Method to get the communication error and the command error

	Method to get the communication error and the command error
Only the error about the internal processing of this function will be returned as return value. The communication error is notified to the callback function registered using the `SFXPOP3::Connect` function. To check whether the command succeeded or not, use the `SFXPOP3::IsResponseOk` or `SFXPOP3::IsResponseErr` function.

Only the error about the internal processing of this function will be returned as return value.

The communication error is notified to the callback function registered using the SFXPOP3::Connect function.

To check whether the command succeeded or not, use the SFXPOP3::IsResponseOk or SFXPOP3::IsResponseErr function.

Reference

SFXPOP3::IsResponseOk | SFXPOP3::IsResponseErr | SFXPOP3::Connect

SFXPOP3::SetSSLMode

Set the SSL connection mode.

[ public ]
Void SetSSLMode(
    Bool isSSL   // whether to use the SSL connection or not
);

Description

To use SSL connection, set true to the "isSSL" parameter.

SFXPOP3::SetTrustMode

Set the SSL trust mode.

[ public ]
SFCError SetTrustMode(
    UInt32 sslTrustMode   // SSL trust mode
);

Return value

Success : SFERR_NO_ERROR
If socket has been closed : SFERR_INVALID_STATE

Description

One of the following values are available for the SSL trust mode:

SSL_TRUST_MODE_FAIL: Default, fail on trust errors.
SSL_TRUST_MODE_CHECK: Suspend on trust errors so they can be checked and ignored.
SSL_TRUST_MODE_IGNORE: Ignore all trust errors.
SSL_TRUST_MODE_ALWAYS: Always suspend so trust can always be checked.

	Note
	Detailed information: ISSL_NegotiateV in the BREW API Reference

Reference

BREW API ISSL_NegotiateV | SFXSSLSocket::SetTrustMode

SFXPOP3::CallbackSPP

Prototype of callback function.

typedef Void(* SFXPOP3::CallbackSPP)(SFCError error, VoidPtr data)

Description

SFXPOP3::CallbackSPP is the prototype for the callback function used in the SFXPOP3 class. This callback function is registered using the SFXPOP3::Connect function. The result of sending a SMTP mail is notified to this callback function.

As for the 1st argument "error": SFERR_NO_ERROR will be set if receiving a POP3 mail succeeds, but an error code other than SFERR_NO_ERROR will be set if it fails.

As for the 2nd argument "reference": A parameter specified by the SFXPOP3::Connect function (in general, instance of the SFXPOP3 class) is passed.

Reference

SFXPOP3::CallbackSPP | SFXPOP3::Connect

SFXPOP3::NumberSizeRec

Structure to store the result of the SFXPOP3::GetListResponse function.

struct NumberSizeRec {
    SInt32  number;
    UInt32  size;
};
typedef NumberSizeRec&        NumberSizeRecRef;
typedef NumberSizeRec*        NumberSizeRecPtr;
typedef NumberSizeRec*&       NumberSizeRecPtrRef;
typedef NumberSizeRec**       NumberSizeRecHandle;
typedef const NumberSizeRec   NumberSizeRecConst;
typedef const NumberSizeRec&  NumberSizeRecConstRef;
typedef const NumberSizeRec*  NumberSizeRecConstPtr;
typedef const NumberSizeRec*& NumberSizeRecConstPtrRef;
typedef const NumberSizeRec** NumberSizeRecConstHandle;

Description

SFXPOP3::NumberSizeRec is the structure to store the result of the SFXPOP3::GetListResponse function. The "number" variable represents the number of the mail message, and the "size" variable represents the size of the mail message(in octets).

Reference

SFXPOP3::GetListResponse

SFXPOP3::NumberUidlRec

Structure to store the result of the SFXPOP3::GetUidlResponse function.

struct NumberUidlRec {
    SInt32          number;
    SFXAnsiString   uidl;
};
typedef NumberSizeRec&        NumberSizeRecRef;
typedef NumberSizeRec*        NumberSizeRecPtr;
typedef NumberSizeRec*&       NumberSizeRecPtrRef;
typedef NumberSizeRec**       NumberSizeRecHandle;
typedef const NumberSizeRec   NumberSizeRecConst;
typedef const NumberSizeRec&  NumberSizeRecConstRef;
typedef const NumberSizeRec*  NumberSizeRecConstPtr;
typedef const NumberSizeRec*& NumberSizeRecConstPtrRef;
typedef const NumberSizeRec** NumberSizeRecConstHandle;

Description

SFXPOP3::NumberUidlRec is the structure to store the result of the SFXPOP3::GetUidlResponse function. The "number" variable represents the number of the mail message, and the "uidl" variable represents the UIDL of the mail message.

Reference

SFXPOP3::GetUidlResponse