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 instance of the SFXPOP3Receiver class.
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.
Register the callback function for receiving mails using the SFXPOP3Receiver::Receive or SFXPOP3Receiver::ReceiveAndDelete function. The SFXPOP3Receiver::ReceiveAndDelete function deletes mails after receiving them.

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

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

class MyClass {
private:
    SFXPOP3Receiver _receiver;
    CALLBACK_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 completion of receiving mails
    if ((error = _receiver.Receive(CALLBACK_FUNCTION(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 completion of receiving mails
CALLBACK_IMPLEMENT_SFXPOP3RECEIVER(MyClass, POP3Callback, error)
{
    SInt32 i;

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

        // get array of received mails
        const SFXArray<SFXPOP3Receiver::MailInfoPtr>& 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

SFXSMTP | SFXSMTPSender | SFXPOP3 | Mail Receiving

Member

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

Public Functions
`Void`	Cancel( `Void` ) Cancel receiving POP3 mails.
`Void`	Clear( `Void` ) Initialize the instance of the SFXPOP3Receiver class.
`SFCError`	Delete( `CallbackSPP` spp , `VoidPtr` reference ) Delete( `UidlArrayPtr` targetUidlArray , `Bool` invertTarget , `CallbackSPP` spp , `VoidPtr` reference ) Delete( `SFXAnsiStringConstRef` uidl , `CallbackSPP` spp , `VoidPtr` reference ) Delete the mails.
`ProgressEnum`	GetProgress( `Void` ) Get the progress status of receiving POP3 mails.
`MailArrayConstRef`	GetReceivedMailArray( `Void` ) Get the array of received mails.
`UidlArrayConstRef`	GetReceivedUidlArray( `Void` ) Get the UIDL array of received mails.
`SFXPOP3Ref`	GetSFXPOP3( `Void` ) Get the instance of the SFXPOP3 class 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( `UidlArrayPtr` targetUidlArray , `Bool` invertTarget , `CallbackSPP` spp , `VoidPtr` reference ) Receive( `SFXAnsiStringConstRef` targetUidl , `CallbackSPP` spp , `VoidPtr` reference ) Receive the mails.
`SFCError`	ReceiveAndDelete( `CallbackSPP` spp , `VoidPtr` reference ) ReceiveAndDelete( `UidlArrayPtr` targetUidlArray , `Bool` invertTarget , `CallbackSPP` spp , `VoidPtr` reference ) ReceiveAndDelete( `SFXAnsiStringConstRef` targetUidl , `CallbackSPP` spp , `VoidPtr` reference ) Receive the mails, and then delete them.
`SFCError`	SetAccount( `SFXAnsiStringConstRef` user , `SFXAnsiStringConstRef` password , `AuthEnum` auth = AUTH_APOP_AND_USERPASS ) Set an account information (username and password).
`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 Prototype of the callback function.
MailArray Type that represents the array of MailInfo structures obtained by the function.
MailInfo Structure that represents a received mail.
ProgressEnum Constants that show the progress status of receiving POP3 mails.
UidlArray Type that represents the mail array received by function.

SFXPOP3Receiver::SFXPOP3Receiver

Constructor of SFXPOP3Receiver class.

[ public, explicit ]
SFXPOP3Receiver(Void);

Description

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::Receive | SFXPOP3Receiver::Delete | SFXPOP3Receiver::~SFXPOP3Receiver

SFXPOP3Receiver::~SFXPOP3Receiver

Destructor of SFXPOP3Receiver class.

[ public ]
~SFXPOP3Receiver(Void);

Description

When receiving POP3 mails is in progress, release this instance after canceling it using the SFXPOP3Receiver::Cancel function.

Reference

SFXPOP3Receiver::Cancel | SFXPOP3Receiver::SFXPOP3Receiver

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::Receive | SFXPOP3Receiver::Delete | SFXPOP3Receiver::ReceiveAndDelete

SFXPOP3Receiver::Clear

Initialize the instance of the SFXPOP3Receiver class.

[ public ]
Void Clear(Void);

Description

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

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

Success : 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)
	Detailed information: RFC1939 (Post Office Protocol - Version 3)

Reference

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
	Detailed information: `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 SFXArray array of the SFXPOP3Receiver::MailInfo (pointers).

Description

The SFXPOP3Receiver::GetReceivedMailArray function needs to be called after the SFXPOP3Receiver::Receive function.

Reference

SFXPOP3Receiver::MailInfo | SFXPOP3Receiver::Receive | SFXPOP3Receiver::GetReceivedUidlArray

SFXPOP3Receiver::GetReceivedUidlArray

Get the UIDL array of received mails.

[ public, const ]
UidlArrayConstRef GetReceivedUidlArray(Void);

Return value

Return the UIDL array of received mails.

Description

Get the UIDL array of received mails.

The SFXPOP3Receiver::GetReceivedUidlArray function needs to be called after the SFXPOP3Receiver::Receive function.

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

Reference

SFXPOP3Receiver::Receive | SFXPOP3Receiver::GetReceivedMailArray

SFXPOP3Receiver::GetSFXPOP3

Get the instance of the SFXPOP3 class 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 valid : 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
	Detailed information: ISSL_NegotiateV in the BREW API Reference

Reference

BREW API ISSL_NegotiateV | SFXPOP3Receiver::SetTrustMode

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

Success : 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 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)
	Detailed information: RFC1939 ( Post Office Protocol - Version 3 )

Reference

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

SFXPOP3Receiver::ReceiveAndDelete

Receive the mails, and then delete them.

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

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

[ public ]
SFCError ReceiveAndDelete(
    UidlArrayPtr targetUidlArray   // array of UIDLs of the mails to be received
    Bool invertTarget              // whether or not to receive mails 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 specified by targetUidlArray.

false: receive mails specified by targetUidlArray.

true: receive mails not specified by targetUidlArray.

Default: false.

Return value

Success : 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 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

To use the SFXPOP3Receiver::ReceiveAndDelete function is more efficient than to receive the mails by the SFXPOP3Receiver::Receive function and delete them by the SFXPOP3Receiver::Delete function.

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)
	Detailed information: RFC1939 (Post Office Protocol - Version 3)

Reference

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

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

Success : 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::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::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::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.

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 the SFXPOP3Receiver::SetServer function before the SFXPOP3Receiver::Receive, SFXPOP3Receiver::Delete, and SFXPOP3Receiver::ReceiveAndDelete functions.

Reference

SFXPOP3Receiver::SetAccount | SFXPOP3Receiver::Receive | SFXPOP3Receiver::Delete | SFXPOP3Receiver::ReceiveAndDelete

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

Reference

BREW API ISSL_NegotiateV | SFXSSLSocket::SetTrustMode

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::CallbackSPP

Prototype of the callback function.

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

Description

The SFXPOP3Receiver::CallbackSPP function is 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.

As 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.

As 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::MailArray

Type that represents the array of MailInfo structures obtained by the 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.

The SFXPOP3Receiver::MailInfo structure is obtained by the SFXPOP3Receiver::GetReceivedMailArray function.

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

Reference

SFXPOP3Receiver::GetReceivedMailArray

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::UidlArray

Type that represents the mail array received by function.

SFMTYPEDEFALIAS(SFXArray<SFXAnsiStringPtr>, UidlArray)

Description

Similar to SFXArray<SFXAnsiStringPtr>.

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

Reference

SFXPOP3Receiver::GetReceivedUidlArray