SFXPOP3Receiver

Class for receiving a POP3 mail.

#include <SFXPOP3Receiver.h.hpp>

class SFXPOP3Receiver;

SFMTYPEDEFCLASS(SFXPOP3Receiver)

Collaboration diagram

Description

Procedure to receive a POP3 mail

Create the SFXPOP3Receiver instance.
Set the IP address and port number of the POP3 server using the SFXPOP3Receiver::SetServer function.
Set the username and password using the SFXPOP3Receiver::SetAccount function.
If you want to delete mails after receiving, call the SFXPOP3Receiver::SetAutoDelete function specifying "true" as its argument.
Register the callback function for receiving mails using the SFXPOP3Receiver::Receive.

	Precondition
	The POP3 server with the implementation of the UIDL command is required.

Example 828. The method to receive mails using the SFXPOP3Receiver class

class MyClass {
private:
    SFXPOP3Receiver _receiver;
    XALLBACK_DECLARE_SFXPOP3RECEIVER(POP3Callback)
public:
    Void Start(Void);
};

Void MyClass::Start(Void)
{
    // set IP address and port number of POP3 server (domain is automatically resolved)
    _receiver.SetServer(SFXSocketAddress("pop3server.example.com:110"));

    // set username and password
    _receiver.SetAccount("user", "password");

    // register POP3Callback as callback function, and then receive mails
    // POP3Callback function is notified of the completion of receiving mails
    if ((error = _receiver.Receive(XALLBACK_INTERNAL(POP3Callback)))
        != SFERR_NO_ERROR) {
        // callback will never be notifiled to POP3Callback function if error is not SFERR_NO_ERROR
        // error handling for this case
        .....
    }
}

// callback function notified of the completion of receiving mails
XALLBACK_IMPLEMENT_SFXPOP3RECEIVER(MyClass, POP3Callback, error)
{
    SInt32 i;

    if (error == SFERR_NO_ERROR) { 
        // succeed to receive mails

        // get array of received mails
        SFXPOP3Receiver::MailArrayConstRef mailArray = receiver.GetReceivedMailArray();

        // display mail
        TRACE("received %d mails", mailArray.GetSize());

        for (i = 0; i < mailArray.GetSize() ; i++) {

            SFXPOP3Receiver::MailInfoPtr minfo = mailArray[i];

            // display mail size, UIDL, mail message including mail header and mail body
            TRACE("%d, %s, %s", minfo->size, minfo->uidl.GetCString(), minfo->mail.GetCString());

        }
    }
}

Reference

SFXMailMessage | SFXPOP3 | Mail Receiving

Member

Constructor/Destructor
SFXPOP3Receiver( `Void` ) Constructor of the SFXPOP3Receiver class.
~SFXPOP3Receiver( `Void` ) Destructor of the SFXPOP3Receiver class.

Public Functions
`Void`	Cancel( `Void` ) Cancel receiving POP3 mails.
`Void`	Clear( `Void` ) Initialize the SFXPOP3Receiver instance.
`SFCError`	Delete( `CallbackSPP` spp , `VoidPtr` reference ) Delete the mails.
`SFCError`	Delete( `SFXAnsiStringConstRef` uidl , `CallbackSPP` spp , `VoidPtr` reference ) Delete the mails.
`SFCError`	Delete( `UidlArrayPtr` targetUidlArray , `Bool` invertTarget , `CallbackSPP` spp , `VoidPtr` reference ) Delete the mails.
`Bool`	GetAutoDelete( `Void` ) Get the value of flag indicating whether or not to delete the mail when receiving it.
`ProgressEnum`	GetProgress( `Void` ) Get the progress status of receiving POP3 mails.
`MailArrayConstRef`	GetReceivedMailArray( `Void` ) Get the array of received mails.
`SFXPOP3Ref`	GetSFXPOP3( `Void` ) Get the SFXPOP3 instance that is internally used.
`Bool`	GetSSLMode( `Void` ) Get the SSL connection mode.
`UInt32`	GetTrustMode( `Void` ) Get the SSL trust mode.
`SFCError`	Receive( `CallbackSPP` spp , `VoidPtr` reference ) Receive the mails.
`SFCError`	Receive( `SFXAnsiStringConstRef` targetUidl , `CallbackSPP` spp , `VoidPtr` reference ) Receive the mails.
`SFCError`	Receive( `UidlArrayPtr` targetUidlArray , `Bool` invertTarget , `CallbackSPP` spp , `VoidPtr` reference ) Receive the mails.
`SFCError`	SetAccount( `SFXAnsiStringConstRef` user , `SFXAnsiStringConstRef` password , `AuthEnum` auth = AUTH_APOP_AND_USERPASS ) Set an account information (username and password).
`Void`	SetAutoDelete( `Bool` isAutoDelete ) Set the flag indicating whether or not to delete the mail when receiving it.
`Void`	SetLimit( `UInt32` limit ) Set the number of mails that can be received at a time.
`Void`	SetNumberOfLines( `SInt32` number ) Set the number of lines when receiving mails.
`Void`	SetSSLMode( `Bool` isSSL ) Set the SSL connection mode.
`Void`	SetServer( `SFXSocketAddressConstRef` server ) Set the IP address and port number of the POP3 server.
`Void`	SetTrustMode( `UInt32` sslTrustMode ) Set the SSL trust mode.

Types
AuthEnum Constants that represent the POP3 authorization methods.
CallbackSPP Type that represents the callback function to notify the completion of the POP3 mail receiving.
MailArray Type that represents the array of MailInfo structures obtained by the SFXPOP3Receiver::GetReceivedMailArray function.
MailInfo Structure that represents a received mail.
ProgressEnum Constants that show the progress status of receiving POP3 mails.
UidlArray Type that represents an array of unique identifiers.

SFXPOP3Receiver::SFXPOP3Receiver

Constructor of the SFXPOP3Receiver class.

[ public, explicit ]
SFXPOP3Receiver(Void);

Description

This constructor does the initialization as follows:

Initialize the progress status of the POP3 mail receiving with PROGRESS_NONE(SFXPOP3Receiver::ProgressEnum).
Initialize the pointer to the UIDL array for receiving mails with null(see: SFXPOP3Receiver::Receive).
Make mails not be deleted when received(see: SFXPOP3Receiver::SetAutoDelete).
Set the POP3 authorization to AUTH_NONE(see: SFXPOP3Receiver::AuthEnum).
Make the number of mails to be received unlimited(see: SFXPOP3Receiver::SetLimit).
Make the number of lines of the received mail unlimited(see: SFXPOP3Receiver::SetNumberOfLines).
Turn the SSL connection mode off(see: SFXPOP3Receiver::SetSSLMode).
Set the SSL trust mode to SSL_TRUST_MODE_FAIL(see: SFXPOP3Receiver::SetTrustMode).

	Note
	The resources necessary to receive POP3 mails are not allocated immediately after the SFXPOP3Receiver instance is created by this constructor. When calling the `SFXPOP3Receiver::Receive` or `SFXPOP3Receiver::Delete` function, those resources will be allocated.

Reference

SFXPOP3Receiver::~SFXPOP3Receiver

Destructor of the SFXPOP3Receiver class.

[ public ]
~SFXPOP3Receiver(Void);

Description

This destructor calls the SFXPOP3Receiver::Cancel function to cancel the POP3 mail receiving.

Reference

SFXPOP3Receiver::Cancel

SFXPOP3Receiver::Cancel

Cancel receiving POP3 mails.

[ public ]
Void Cancel(Void);

Description

Interrupt and end the POP3 mail receiving, then release all the allocated resource.

Reference

SFXPOP3Receiver::Clear

Initialize the SFXPOP3Receiver instance.

[ public ]
Void Clear(Void);

Description

Initialize the setting information on the POP3 server, the received mails, and the internal variables of the SFXPOP3Receiver instance.

	Note
	This function is called in the `SFXPOP3Receiver::Cancel` function internally.

Reference

SFXPOP3Receiver::SetAccount | SFXPOP3Receiver::Cancel

SFXPOP3Receiver::Delete

Delete the mails.

[ public ]
SFCError Delete(
    CallbackSPP spp     // callback function
    VoidPtr reference   // data passed to callback function
);

[ public ]
SFCError Delete(
    SFXAnsiStringConstRef uidl   // UIDL of deleted mail
    CallbackSPP spp              // callback function
    VoidPtr reference            // data passed to callback function
);

[ public ]
SFCError Delete(
    UidlArrayPtr targetUidlArray   // array of UIDL of deleted mails
    Bool invertTarget              // whether or not to delete mails other than specified ones
    CallbackSPP spp                // callback function
    VoidPtr reference              // data passed to callback function
);

Argument

uidl: UIDL of deleted mail.

targetUidlArray

Mail UIDL array that becomes the target. If null is set, all the mails in POP3 server are specified.

It is null by default.

invertTarget

Whether or not to delete mails other than the specified ones.

false: delete mails specified by targetUidlArray.

true: delete mails not specified by targetUidlArray.

Default: false.

Return value

If succeeds: SFERR_NO_ERROR
If invalid parameter: SFERR_INVALID_PARAM
If receiving is in progress, or socket has already been opened, or connection establishment failed: SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY
If failed: SFERR_FAILED
If failed to creating a socket: AEE_NET_ERROR
If password is not correct: SFERR_MAIL_INVALID_PASSWORD(0x6801)
If server does not support the UIDL command: SFERR_MAIL_NOT_SUPPORT_UIDL(0x6802)

Description

	Result of deleteing POP3 mails
	The result of deleteing POP3 mails is notified to the callback function. It is not reflected in the return value of the SFXPOP3Receiver::Delete function.

	About UIDL (Unique-ID Listing)
	Reference: RFC1939 (Post Office Protocol - Version 3)

Reference

SFXPOP3Receiver::Receive

SFXPOP3Receiver::GetAutoDelete

Get the value of flag indicating whether or not to delete the mail when receiving it.

[ public, const ]
Bool GetAutoDelete(Void);

Reference

SFXPOP3Receiver::SetAutoDelete | SFXPOP3Receiver::Receive

SFXPOP3Receiver::GetProgress

Get the progress status of receiving POP3 mails.

[ public, const ]
ProgressEnum GetProgress(Void);

Return value

Return the progress status of receiving POP3 mails.

	About the return value of SFXPOP3Receiver::GetProgress function
	Reference: `SFXPOP3Receiver::ProgressEnum`

Description

If receiving POP3 mails failed, call the SFXPOP3Receiver::GetProgress function in the callback function to get the stage where an error occurred.

Reference

SFXPOP3Receiver::ProgressEnum

SFXPOP3Receiver::GetReceivedMailArray

Get the array of received mails.

[ public, const ]
MailArrayConstRef GetReceivedMailArray(Void);

Return value

Return the array of received mail messages(SFXPOP3Receiver::MailArray).

Description

This function needs to be called in the callback specified in the spp argument of the SFXPOP3Receiver::Receive function.

Reference

SFXPOP3Receiver::MailArray | SFXPOP3Receiver::MailInfo | SFXPOP3Receiver::Receive

SFXPOP3Receiver::GetSFXPOP3

Get the SFXPOP3 instance that is internally used.

[ public ]
SFXPOP3Ref GetSFXPOP3(Void);

Reference

SFXPOP3

SFXPOP3Receiver::GetSSLMode

Get the SSL connection mode.

[ public, const ]
Bool GetSSLMode(Void);

Return value

If the SSL connection mode is turned on: true
If invalid : false

Reference

SFXPOP3Receiver::SetSSLMode

SFXPOP3Receiver::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
	Reference: ISSL_NegotiateV in the BREW API Reference

Reference

SFXPOP3Receiver::SetTrustMode | BREW API ISSL_NegotiateV

SFXPOP3Receiver::Receive

Receive the mails.

[ public ]
SFCError Receive(
    CallbackSPP spp     // callback function
    VoidPtr reference   // data passed to callback function
);

[ public ]
SFCError Receive(
    SFXAnsiStringConstRef targetUidl   // received UIDL of mail
    CallbackSPP spp                    // callback function
    VoidPtr reference                  // data passed to callback function
);

[ public ]
SFCError Receive(
    UidlArrayPtr targetUidlArray   // array of UIDLs of received mails
    Bool invertTarget              // whether or not to receive mail other than the specified ones
    CallbackSPP spp                // callback function
    VoidPtr reference              // data passed to callback function
);

Argument

targetUidl: Specify the UIDL of the mail to be received.

targetUidlArray

array of the UIDLs of the mails to be received.

If null is set, it is regarded that all the mail in the POP3 server will be received.

This argument is null by default.

invertTarget

Whether or not to receive mails other than the specified ones.

false: receive mails specified by targetUidlArray.

true: receive mails not specified by targetUidlArray.

Default: false.

Return value

If succeeds: SFERR_NO_ERROR
If the uidl argument is the null string: SFERR_INVALID_PARAM
If receiving is in progress, or socket has already been opened, or connection establishment failed: SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY
If failed to create a socket: AEE_NET_ERROR
If password is not correct: SFERR_MAIL_INVALID_PASSWORD(0x6801)
If server does not support the UIDL command: SFERR_MAIL_NOT_SUPPORT_UIDL(0x6802)

Description

Get the received mails from the SFXPOP3Receiver::MailInfo array obtained by the SFXPOP3Receiver::GetReceivedMailArray function.

	Result of receiving POP3 mails
	Result of receiving POP3 mails is notified to the callback function. It is not reflected in the return value of the SFXPOP3Receiver::Receive function.

	About UIDL (Unique-ID Listing)
	Reference: RFC1939 ( Post Office Protocol - Version 3 )

Reference

SFXPOP3Receiver::GetReceivedMailArray | SFXPOP3Receiver::Delete | SFXPOP3Receiver::MailInfo | SFXPOP3Receiver::SFXPOP3Receiver

SFXPOP3Receiver::SetAccount

Set an account information (username and password).

[ public ]
SFCError SetAccount(
    SFXAnsiStringConstRef user               // username
    SFXAnsiStringConstRef password           // password
    AuthEnum auth = AUTH_APOP_AND_USERPASS   // authorization method
);

Argument

user: Username.
password: Password.

Return value

If succeeds: SFERR_NO_ERROR
If insufficient memory: SFERR_NO_MEMOERY

Description

Call the SFXPOP3Receiver::SetAccount function before the SFXPOP3Receiver::Receive or SFXPOP3Receiver::Delete function.

Reference

SFXPOP3Receiver::SetServer | SFXPOP3Receiver::Receive | SFXPOP3Receiver::Delete | SFXPOP3Receiver::AuthEnum

SFXPOP3Receiver::SetAutoDelete

Set the flag indicating whether or not to delete the mail when receiving it.

[ public ]
Void SetAutoDelete(
    Bool isAutoDelete   // whether or not to delete the mail
);

Description

This function sets the flag indicating whether or not to delete the mail when receiving it using the SFXPOP3Receiver::Receive function.

Default: false

Reference

SFXPOP3Receiver::GetAutoDelete | SFXPOP3Receiver::SFXPOP3Receiver

SFXPOP3Receiver::SetLimit

Set the number of mails that can be received at a time.

[ public ]
Void SetLimit(
    UInt32 limit   
);

Description

Set the number of mails to receive at a time.

Reference

SFXPOP3Receiver::SetNumberOfLines | SFXPOP3Receiver::SFXPOP3Receiver

SFXPOP3Receiver::SetNumberOfLines

Set the number of lines when receiving mails.

[ public ]
Void SetNumberOfLines(
    SInt32 number   // the number of lines
);

Description

Only the number of lines (set by the SetNumberOfLines function) from the head are received.

Reference

SFXPOP3Receiver::SetLimit | SFXPOP3Receiver::SFXPOP3Receiver

SFXPOP3Receiver::SetSSLMode

Set the SSL connection mode.

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

Description

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

Reference

SFXPOP3Receiver::GetSSLMode | SFXPOP3Receiver::SFXPOP3Receiver

SFXPOP3Receiver::SetServer

Set the IP address and port number of the POP3 server.

[ public ]
Void SetServer(
    SFXSocketAddressConstRef server   // IP address and port number of the POP3 server
);

Argument

server: POP3 server's IP address and port number.

Description

Call this function before the SFXPOP3Receiver::Receive, SFXPOP3Receiver::Delete, and SFXPOP3Receiver::SetAutoDelete functions.

Reference

SFXPOP3Receiver::Receive | SFXPOP3Receiver::Delete | SFXPOP3Receiver::SFXPOP3Receiver | SFXSocketAddress

SFXPOP3Receiver::SetTrustMode

Set the SSL trust mode.

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

Argument

sslTrustMode

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
	Reference: ISSL_NegotiateV in the BREW API Reference

Reference

SFXPOP3Receiver::Cancel | SFXPOP3Receiver::SFXPOP3Receiver | SFXSSLSocket::SetTrustMode | BREW API ISSL_NegotiateV

SFXPOP3Receiver::AuthEnum

Constants that represent the POP3 authorization methods.

enum AuthEnum {
    AUTH_APOP_AND_USERPASS,
    AUTH_ONLY_APOP,
    AUTH_ONLY_USERPASS
};

Description

To set the POP3 authorization method, use the SFXPOP3Receiver::SetAccount function.

AUTH_APOP_AND_USERPASS: The APOP authorization is performed. If failed, the username/password authorization is performed.
AUTH_ONLY_APOP: Only the APOP authorization is performed.
AUTH_ONLY_USERPASS: Only the username/password authorization is performed.

Reference

SFXPOP3Receiver::SetAccount | SFXPOP3Receiver::Receive | SFXPOP3Receiver::SFXPOP3Receiver

SFXPOP3Receiver::CallbackSPP

Type that represents the callback function to notify the completion of the POP3 mail receiving.

typedef Void(* SFXPOP3Receiver::CallbackSPP)(SFCError error, VoidPtr reference)

Description

This function prototype represents the callback function called when receiving POP3 mails is finished.

To register this function, use the SFXPOP3Receiver::Receive or SFXPOP3Receiver::Delete function.

The result of receiving POP3 mails is obtained in this callback function.

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

For the 2nd argument "reference": Specify the "reference" argument of the SFXPOP3Receiver::Receive or SFXPOP3Receiver::Delete function (in general, instance of the SFXPOP3Receiver class).

Reference

SFXPOP3Receiver | SFXPOP3Receiver::Delete | SFXPOP3Receiver::GetReceivedMailArray | SFXPOP3Receiver::GetProgress

SFXPOP3Receiver::MailArray

Type that represents the array of MailInfo structures obtained by the SFXPOP3Receiver::GetReceivedMailArray function.

SFMTYPEDEFALIAS(SFXArray<MailInfoPtr>, MailArray)

Description

Similar to SFXArray<MailInfoPtr>.

Reference

SFXPOP3Receiver::GetReceivedMailArray

SFXPOP3Receiver::MailInfo

Structure that represents a received mail.

struct MailInfo {
    UInt32          size;
    SFXAnsiString   uidl;
    SFXAnsiString   mail;
};

Description

The "size" variable is the size of the mail, the "uidl" variable is the UIDL of the mail, and the "mail" variable is the data of the mail.

This structure is obtained by the SFXPOP3Receiver::GetReceivedMailArray function.

	Aboout UIDL (Unique-ID Listing)
	Reference: RFC1939 (Post Office Protocol - Version 3)

Reference

SFXPOP3Receiver::GetReceivedMailArray | SFXMailMessage::Parse | SFXMailMessage

SFXPOP3Receiver::ProgressEnum

Constants that show the progress status of receiving POP3 mails.

enum ProgressEnum {
    PROGRESS_NONE,
    PROGRESS_CONNECT,
    PROGRESS_USER,
    PROGRESS_PASS,
    PROGRESS_LIST,
    PROGRESS_UIDL,
    PROGRESS_TOP,
    PROGRESS_RETR,
    PROGRESS_DELE,
    PROGRESS_QUIT,
    PROGRESS_DONE
};

Description

Constants that show the progress status of receiving POP3 mail with the SFXPOP3Receiver.

The following values can be obtained using SFXPOP3Receiver::GetProgress function.

PROGRESS_NONE: The connection is not started.
PROGRESS_CONNECT: Connection to POP3 server is in progress.
PROGRESS_USER: Waiting for the response of the USER command.
PROGRESS_PASS: Waiting for the response of the PASS command.
PROGRESS_LIST: Waiting for the response of the LIST command.
PROGRESS_UIDL: Waiting for the response of the UIDL command.
PROGRESS_RETR: Waiting for the response of the RETR command.
PROGRESS_TOP: Waiting for the response of the TOP command.
PROGRESS_DELE: Waiting for the response of the DELE command.
PROGRESS_QUIT: Waiting for the response of the QUIT command.
PROGRESS_DONE: Receiving POP3 mails is finished.

Reference

SFXPOP3Receiver::GetProgress | SFXPOP3Receiver::SFXPOP3Receiver

SFXPOP3Receiver::UidlArray

Type that represents an array of unique identifiers.

SFMTYPEDEFALIAS(SFXArray<SFXAnsiStringPtr>, UidlArray)

Description

Similar to SFXArray<SFXAnsiStringPtr>.

	About UIDL (Unique-ID Listing)
	Reference: RFC1939 (Post Office Protocol - Version 3)