SFXPOP3

Class for processing the POP3 protocol.

#include <SFXPOP3.h.hpp>

class SFXPOP3;

SFMTYPEDEFCLASS(SFXPOP3)

Collaboration diagram

Description

Procedure to receive a POP3 mail

Create the SFXPOP3 instance. 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.

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

Example 827. Implementation of the SFXPOP3Receiver class

/***************************************************************************************
****************************************************************************************
***
***     File            : SFXPOP3Receiver.f.hpp
***
****************************************************************************************
****************************************************************************************/

#ifndef __SOPHIAFRAMEWORK_SFXPOP3RECEIVER_FHPP
#define __SOPHIAFRAMEWORK_SFXPOP3RECEIVER_FHPP

#include <SFXGeneral/SFXEnvironment.h.hpp>

SFMTYPEDEFCLASS(SFXPOP3Receiver)

#endif // __SOPHIAFRAMEWORK_SFXPOP3RECEIVER_FHPP //


/***************************************************************************************
****************************************************************************************
***
***     File            : SFXPOP3Receiver.h.hpp
***
****************************************************************************************
****************************************************************************************/

#ifndef __SOPHIAFRAMEWORK_SFXPOP3RECEIVER_HHPP
#define __SOPHIAFRAMEWORK_SFXPOP3RECEIVER_HHPP

#include <SFXGeneral/SFXEnvironment.h.hpp>
#include <SFXProtocol/SFXMail/SFXPOP3Receiver.f.hpp>
#include <SFXProtocol/SFXMail/SFXPOP3.h.hpp>
#include <SFXCollection/SFXArray.h.hpp>

class SFXPOP3Receiver {
    SFMSEALCOPY(SFXPOP3Receiver)
    public:
        enum ProgressEnum {
            PROGRESS_NONE                       = 0,
            PROGRESS_CONNECT,
            PROGRESS_USER,
            PROGRESS_PASS,
            PROGRESS_LIST,
            PROGRESS_UIDL,
            PROGRESS_TOP,
            PROGRESS_RETR,
            PROGRESS_DELE,
            PROGRESS_QUIT,
            PROGRESS_DONE
        };
        enum AuthEnum {
            AUTH_NONE                           = 0,
            AUTH_APOP_AND_USERPASS,
            AUTH_ONLY_APOP,
            AUTH_ONLY_USERPASS
        };
    private:
        enum StateEnum {
            STATE_STANDBY                       = 0,
            STATE_RECEIVING
        };

    public:
        typedef Void                            (*CallbackSPP)                  (SFCError error, VoidPtr reference);
        SFMTYPEDEFSTRUCT(MailInfo)
        struct MailInfo {
            UInt32                              size;
            SFXAnsiString                       uidl;
            SFXAnsiString                       mail;
        };
        SFMTYPEDEFALIAS(SFXArray<SFXAnsiStringPtr>, UidlArray)
        SFMTYPEDEFALIAS(SFXArray<MailInfoPtr>, MailArray)

    private:
                StateEnum                       _state;
                ProgressEnum                    _progress;
                CallbackSPP                     _spp;
                VoidPtr                         _reference;
                SFXPOP3                         _pop3;
                SFXSocketAddress                _server;
                SFXAnsiString                   _user;
                SFXAnsiString                   _password;
                SInt32                          _line;
                UInt32                          _limit;
                UidlArray                       _singleUidlArray;
                UidlArrayPtr                    _targetUidlArray;
                Bool                            _invertTarget;
                Bool                            _isAutoDelete;
                SInt32                          _deleteCandNum;
                Bool                            _noUidl;
                AuthEnum                        _auth;
                Bool                            _apop;
                MailArray                       _receivedMailArray;
                SFXPOP3::NumberSizeRecPtr       _numSizeList;
                SInt32                          _numSizeCount;
                SFXPOP3::NumberUidlRecPtr       _numUidlList;
                SInt32                          _numUidlCount;
                SInt32                          _numSizeIndex;
                UInt32                          _index;
                MailInfo                        _nextMailInfo;
                Bool                            _isSSL;
                UInt32                          _sslTrustMode;

    public:
        explicit                                SFXPOP3Receiver                 (Void);
                                                ~SFXPOP3Receiver                (Void);
                SFXPOP3Ref                      GetSFXPOP3                      (Void);
                ProgressEnum                    GetProgress                     (Void) const;
                Void                            SetSSLMode                      (Bool isSSL);
                Bool                            GetSSLMode                      (Void) const;
                Void                            SetTrustMode                    (UInt32 sslTrustMode);
                UInt32                          GetTrustMode                    (Void) const;
                Void                            SetAutoDelete                   (Bool isAutoDelete);
                Bool                            GetAutoDelete                   (Void) const;
                Void                            Cancel                          (Void);
                Void                            Clear                           (Void);
                Void                            SetServer                       (SFXSocketAddressConstRef server);
                Void                            SetLimit                        (UInt32 limit);
                Void                            SetNumberOfLines                (SInt32 number);
                SFCError                        SetAccount                      (SFXAnsiStringConstRef user, SFXAnsiStringConstRef password, AuthEnum auth = AUTH_APOP_AND_USERPASS);
                SFCError                        Receive                         (CallbackSPP spp, VoidPtr reference);
                SFCError                        Receive                         (SFXAnsiStringConstRef targetUidl, CallbackSPP spp, VoidPtr reference);
                SFCError                        Receive                         (UidlArrayPtr targetUidlArray, Bool invertTarget, CallbackSPP spp, VoidPtr reference);
                SFCError                        Delete                          (CallbackSPP spp, VoidPtr reference);
                SFCError                        Delete                          (SFXAnsiStringConstRef uidl, CallbackSPP spp, VoidPtr reference);
                SFCError                        Delete                          (UidlArrayPtr targetUidlArray, Bool invertTarget, CallbackSPP spp, VoidPtr reference);
                MailArrayConstRef               GetReceivedMailArray            (Void) const;
    private:
                SFCError                        ProceedConnect                  (Void);
                SFCError                        ProceedUser                     (Void);
                SFCError                        ProceedPass                     (Void);
                SFCError                        ProceedList                     (Void);
                SFCError                        ProceedUidl                     (Bool receiving);
                SFCError                        ProceedReceivingRetr            (Void);
                SFCError                        SendAuthCommand                 (Void);
                SFCError                        ReceiveNextMail                 (BoolPtr next);
                SFCError                        DeleteNextMail                  (BoolPtr next);
                Void                            Finish                          (SFCError error);
                SFCError                        SetSingleUidl                   (SFXAnsiStringConstRef uidl);
                Void                            FreeNumSizeList                 (Void);
                Void                            FreeNumUidlList                 (Void);
                Void                            FreeSingleUidl                  (Void);
                Bool                            IsTargetUidl                    (SFXAnsiStringConstRef uidl);
                SInt32                          FindNextTarget                  (Void);
                XALLBACK_DECLARE_SFXPOP3(OnPOP3Receive)
                XALLBACK_DECLARE_SFXPOP3(OnPOP3Delete)
};

#define     XALLBACK_DECLARE_SFXPOP3RECEIVER(FUNCTION)                          XALLBACK_DECLARE_SFXPOP3(FUNCTION)

#include <SFXProtocol/SFXMail/SFXPOP3Receiver.i.hpp>

#endif // __SOPHIAFRAMEWORK_SFXPOP3RECEIVER_HHPP //


/***************************************************************************************
****************************************************************************************
***
***     File            : SFXPOP3Receiver.i.hpp
***
****************************************************************************************
****************************************************************************************/

#ifndef __SOPHIAFRAMEWORK_SFXPOP3RECEIVER_IHPP
#define __SOPHIAFRAMEWORK_SFXPOP3RECEIVER_IHPP

#include <SFXGeneral/SFXEnvironment.h.hpp>

/*public */inline SFXPOP3Ref SFXPOP3Receiver::GetSFXPOP3(Void)
{
    return _pop3;
}// SFXPOP3Receiver::GetSFXPOP3 //

/*public */inline SFXPOP3Receiver::ProgressEnum SFXPOP3Receiver::GetProgress(Void) const
{
    return _progress;
}// SFXPOP3Receiver::GetProgress //

/*public */inline Void SFXPOP3Receiver::SetSSLMode(Bool isSSL)
{
    _isSSL = isSSL;
    return;
}// SFXPOP3Receiver::SetSSLMode //

/*public */inline Bool SFXPOP3Receiver::GetSSLMode(Void) const
{
    return _isSSL;
}// SFXPOP3Receiver::GetSSLMode //

/*public */inline Void SFXPOP3Receiver::SetTrustMode(UInt32 sslTrustMode)
{
    _sslTrustMode = sslTrustMode;
    return;
}// SFXPOP3Receiver::SetTrustMode //

/*public */inline UInt32 SFXPOP3Receiver::GetTrustMode(Void) const
{
    return _sslTrustMode;
}// SFXPOP3Receiver::GetTrustMode //

/*public */inline Void SFXPOP3Receiver::SetAutoDelete(Bool isAutoDelete)
{
    _isAutoDelete = isAutoDelete;
    return;
}// SFXPOP3Receiver::SetAutoDelete //

/*public */inline Bool SFXPOP3Receiver::GetAutoDelete(Void) const
{
    return _isAutoDelete;
}// SFXPOP3Receiver::GetAutoDelete //

/*public */inline Void SFXPOP3Receiver::SetServer(SFXSocketAddressConstRef server)
{
    _server.Set(server);
}// SFXPOP3Receiver::SetServer //

/*public */inline Void SFXPOP3Receiver::SetLimit(UInt32 limit)
{
    _limit = limit;
}// SFXPOP3Receiver::SetLimit //

/*public */inline Void SFXPOP3Receiver::SetNumberOfLines(SInt32 number)
{
    _line = number;
}// SFXPOP3Receiver::SetNumberOfLines //

/*public */inline SFCError SFXPOP3Receiver::Receive(CallbackSPP spp, VoidPtr reference)
{
    return Receive(null, false, spp, reference);
}// SFXPOP3Receiver::Receive //

/*public */inline SFCError SFXPOP3Receiver::Delete(CallbackSPP spp, VoidPtr reference)
{
    return Delete(null, false, spp, reference);
}// SFXPOP3Receiver::Delete //

/*public */inline SFXPOP3Receiver::MailArrayConstRef SFXPOP3Receiver::GetReceivedMailArray(Void) const
{
    return _receivedMailArray;
}// SFXPOP3Receiver::GetReceivedMailArray //

#define     XALLBACK_IMPLEMENT_SFXPOP3RECEIVER(TYPE, FUNCTION, ERROR)           XALLBACK_IMPLEMENT_SFXPOP3(TYPE, FUNCTION, ERROR)

#endif // __SOPHIAFRAMEWORK_SFXPOP3RECEIVER_IHPP //


/***************************************************************************************
****************************************************************************************
***
***     File            : SFXPOP3Receiver.i.cpp
***
****************************************************************************************
****************************************************************************************/

#include <SFXProtocol/SFXMail/SFXPOP3Receiver.h.hpp>

/*public */SFXPOP3Receiver::SFXPOP3Receiver(Void) : _state(STATE_STANDBY), _progress(PROGRESS_NONE), _line(-1), _limit(0), _targetUidlArray(null), _isAutoDelete(false), _deleteCandNum(0), _noUidl(false), _auth(AUTH_NONE), _numSizeList(null), _numUidlList(null), _isSSL(false), _sslTrustMode(SSL_TRUST_MODE_FAIL)
{
}// SFXPOP3Receiver::SFXPOP3Receiver //

/*public */SFXPOP3Receiver::~SFXPOP3Receiver(Void)
{
    Cancel();
}// SFXPOP3Receiver::~SFXPOP3Receiver //

/*public */Void SFXPOP3Receiver::Cancel(Void)
{
    _state = STATE_STANDBY;
    _progress = PROGRESS_NONE;
    _spp = null;
    _reference = null;
    _pop3.Close();
    Clear();
    return;
}// SFXPOP3Receiver::Cancel //

/*public */Void SFXPOP3Receiver::Clear(Void)
{
    MailArray::Iterator itor;
    SFXAnsiStringPtr string;
    MailInfoPtr minfo;

    _server.Set(0, 0);
    _user.Clear();
    _password.Clear();

    itor = _receivedMailArray.GetFirstIterator();
    while (itor.HasNext()) {
        minfo = itor.GetNext();
        ::delete minfo;
    }
    _receivedMailArray.Clear();
    FreeSingleUidl();
    FreeNumSizeList();
    FreeNumUidlList();
    return;
}// SFXPOP3Receiver::Clear //

/*public */SFCError SFXPOP3Receiver::SetAccount(SFXAnsiStringConstRef user, SFXAnsiStringConstRef password, AuthEnum auth)
{
    SFCError error;

    if ((error = _user.Set(user)) == SFERR_NO_ERROR) {
        if ((error = _password.Set(password)) == SFERR_NO_ERROR) {
            _auth = auth;
        }
    }
    return error;
}// SFXPOP3Receiver::SetAccount //

/*public */SFCError SFXPOP3Receiver::Receive(SFXAnsiStringConstRef targetUidl, CallbackSPP spp, VoidPtr reference)
{
    SFCError error;

    if (!targetUidl.IsEmpty()) {
        if ((error = SetSingleUidl(targetUidl)) == SFERR_NO_ERROR) {
            error = Receive(&_singleUidlArray, false, spp, reference);
        }
    }
    else {
        error = SFERR_INVALID_PARAM;
    }
    return error;
}// SFXPOP3Receiver::Receive //

/*public */SFCError SFXPOP3Receiver::Receive(UidlArrayPtr targetUidlArray, Bool invertTarget, CallbackSPP spp, VoidPtr reference)
{
    SFCError error;

    if (_state == STATE_STANDBY) {
        _targetUidlArray = targetUidlArray;
        _invertTarget = invertTarget;
        _apop = false;
        _spp = spp;
        _reference = reference;
        _pop3.Close();
        if ((error = _pop3.Open()) == SFERR_NO_ERROR) {
            _pop3.SetSSLMode(_isSSL);
            if ((error = _pop3.SetTrustMode(_sslTrustMode)) == SFERR_NO_ERROR) {
                if ((error = _pop3.Connect(_server, XALLBACK_INTERNAL(OnPOP3Receive))) == SFERR_NO_ERROR) {
                    _state = STATE_RECEIVING;
                    _progress = PROGRESS_CONNECT;
                }
            }
            if (error != SFERR_NO_ERROR) {
                _pop3.Close();
            }
        }
    }
    else {
        error = SFERR_INVALID_STATE;
    }
    return error;
}// SFXPOP3Receiver::Receive //

/*public */SFCError SFXPOP3Receiver::Delete(SFXAnsiStringConstRef uidl, CallbackSPP spp, VoidPtr reference)
{
    SFCError error;

    if (!uidl.IsEmpty()) {
        if ((error = SetSingleUidl(uidl)) == SFERR_NO_ERROR) {
            error = Delete(&_singleUidlArray, false, spp, reference);
        }
    }
    else {
        error = SFERR_INVALID_PARAM;
    }
    return error;
}// SFXPOP3Receiver::Delete //

/*public */SFCError SFXPOP3Receiver::Delete(UidlArrayPtr targetUidlArray, Bool invertTarget, CallbackSPP spp, VoidPtr reference)
{
    SFCError error;

    if (_state == STATE_STANDBY) {
        _targetUidlArray = targetUidlArray;
        _invertTarget = invertTarget;
        _spp = spp;
        _reference = reference;
        _pop3.Close();
        if ((error = _pop3.Open()) == SFERR_NO_ERROR) {
            _pop3.SetSSLMode(_isSSL);
            if ((error = _pop3.SetTrustMode(_sslTrustMode)) == SFERR_NO_ERROR) {
                if ((error = _pop3.Connect(_server, XALLBACK_INTERNAL(OnPOP3Delete))) == SFERR_NO_ERROR) {
                    _state = STATE_RECEIVING;
                    _progress = PROGRESS_CONNECT;
                }
            }
            if (error != SFERR_NO_ERROR) {
                _pop3.Close();
            }
        }
    }
    else {
        error = SFERR_INVALID_STATE;
    }
    return error;
}// SFXPOP3Receiver::Delete //

/*private */XALLBACK_IMPLEMENT_SFXPOP3(SFXPOP3Receiver, OnPOP3Receive, error)
{
    Bool next;

    if (error == SFERR_NO_ERROR) {
        switch (_progress) {
            case PROGRESS_CONNECT:
                error = ProceedConnect();
                break;
            case PROGRESS_USER:
                error = ProceedUser();
                break;
            case PROGRESS_PASS:
                error = ProceedPass();
                break;
            case PROGRESS_LIST:
                error = ProceedList();
                break;
            case PROGRESS_UIDL:
                error = ProceedUidl(true);
                break;
            case PROGRESS_RETR:
            case PROGRESS_TOP:
                error = ProceedReceivingRetr();
                break;
            case PROGRESS_DELE:
                if (_pop3.IsResponseOk()) {
                    if ((error = ReceiveNextMail(&next)) == SFERR_NO_ERROR) {
                        if (!next) {
                            _progress = PROGRESS_QUIT;
                            error = _pop3.SendQuitCommand();
                        }
                    }
                }
                else {
                    error = SFERR_FAILED;
                }
                break;
            case PROGRESS_QUIT:
                if (_pop3.IsResponseOk()) {
                    _progress = PROGRESS_DONE;
                    Finish(SFERR_NO_ERROR);
                }
                else {
                    error = SFERR_FAILED;
                }
                break;
            case PROGRESS_DONE:
            case PROGRESS_NONE:
            default:
                error = SFERR_FAILED;
                break;
        }
    }
    if (error != SFERR_NO_ERROR) {
        Finish(error);
    }
    return;
}// XALLBACK_IMPLEMENT_SFXPOP3(SFXPOP3Receiver, OnPOP3, error) //

/*private */SFCError SFXPOP3Receiver::ProceedConnect(Void)
{
    SFCError error;

    if (_auth == AUTH_NONE || _user.IsEmpty() && _password.IsEmpty()) {
// skip user authorization
        _progress = PROGRESS_LIST;
        error = _pop3.SendListCommand();
    }
    else {
        error = SendAuthCommand();
    }
    return error;
}// SFXPOP3Receiver::ProceedConnect //

/*private */SFCError SFXPOP3Receiver::ProceedUser(Void)
{
    SFCError error;

    if (_pop3.IsResponseOk()) {
        _progress = PROGRESS_PASS;
        error = _pop3.SendPassCommand(_password);
    }
    else {
        error = SFERR_FAILED;
    }
    return error;
}// SFXPOP3Receiver::ProceedUser //

/*private */SFCError SFXPOP3Receiver::ProceedPass(Void)
{
    SFCError error;

    if (_pop3.IsResponseOk()) {
        _progress = PROGRESS_LIST;
        error = _pop3.SendListCommand();
    }
    else {
        if (_apop && _auth == AUTH_APOP_AND_USERPASS) {
// The server does not support APOP.
            _apop = false;
            _progress = PROGRESS_USER;
            error = _pop3.SendUserCommand(_user);
        }
        else {
            error = SFERR_MAIL_INVALID_PASSWORD;
        }
    }
    return error;
}//SFXPOP3Receiver::ProceedPass //

/*private */SFCError SFXPOP3Receiver::ProceedList(Void)
{
    SFCError error;

    if (_pop3.IsResponseOk()) {
        FreeNumSizeList();
        if ((error = _pop3.GetListResponse(&_numSizeList, &_numSizeCount)) == SFERR_NO_ERROR) {
            if (_numSizeCount > 0) {
                _progress = PROGRESS_UIDL;
                error = _pop3.SendUidlCommand();
            }
            else {
                _progress = PROGRESS_QUIT;
                error = _pop3.SendQuitCommand();
            }
        }
    }
    else {
        error = SFERR_FAILED;
    }
    return error;
}// SFXPOP3Receiver::ProceedList //

/*private */SFCError SFXPOP3Receiver::ProceedUidl(Bool receiving)
{
    SFCError error(SFERR_NO_ERROR);
    Bool nextMail(false);

    if (!_pop3.IsResponseOk()) {
        if (_targetUidlArray == null && !_invertTarget) {
            _noUidl = true; // The server is not support uidl command.
        }
        else {
            error = SFERR_MAIL_NOT_SUPPORT_UIDL;
        }
    }
    if (error == SFERR_NO_ERROR) {
        FreeNumUidlList();
        if (!_noUidl) {
            error = _pop3.GetUidlResponse(&_numUidlList, &_numUidlCount);
        }
        else {
            _numUidlCount = _numSizeCount;
        }
        if (error == SFERR_NO_ERROR) {
            if (!receiving || _numUidlCount > 0) {
                _index = 0;
                _numSizeIndex = 0;
                error = (receiving) ? (ReceiveNextMail(&nextMail)) : (DeleteNextMail(&nextMail));
            }
            if (error == SFERR_NO_ERROR) {
                if (!nextMail) {
                    error = _pop3.SendQuitCommand();
                }
            }
        }
    }
    return error;
}// SFXPOP3Receiver::ProceedUidl //

/*private */SFCError SFXPOP3Receiver::ProceedReceivingRetr(Void)
{
    SFCError error(SFERR_NO_ERROR);
    MailInfoPtr minfo;
    Bool next;

    if (_pop3.IsResponseOk()) {
        if ((minfo = ::new MailInfo) != null) {
            if ((error = _receivedMailArray.InsertLast(minfo)) == SFERR_NO_ERROR) {
                minfo->size = _nextMailInfo.size;
                if ((error = minfo->uidl.Set(_nextMailInfo.uidl)) == SFERR_NO_ERROR) {
                    if (_progress == PROGRESS_RETR) {
                        error = _pop3.GetRetrResponse(&minfo->mail);
                    }
                    else {
                        error = _pop3.GetTopResponse(&minfo->mail);
                    }
                    if (error == SFERR_NO_ERROR) {
                        ++_index;
                        if (_isAutoDelete) {
                            _progress = PROGRESS_DELE;
                            error = _pop3.SendDeleCommand(_deleteCandNum);
                        }
                        else {
                            if ((error = ReceiveNextMail(&next)) == SFERR_NO_ERROR) {
                                if (!next) {
                                    _progress = PROGRESS_QUIT;
                                    error = _pop3.SendQuitCommand();
                                }
                            }
                        }
                    }
                }
            }
            if (error != SFERR_NO_ERROR) {
                ::delete minfo;
            }
        }
        else {
            error = SFERR_NO_MEMORY;
        }
    }
    else {
        error = SFERR_FAILED;
    }
    return error;
}// SFXPOP3Receiver::ProceedReceivingRetr //

/*private */SFCError SFXPOP3Receiver::ReceiveNextMail(BoolPtr next)
{
    SFCError error(SFERR_NO_ERROR);
    SInt32 number;

    if (_limit > 0 && _index >= _limit) {
        *next = false;
    }
    else {
        if ((number = FindNextTarget()) > -1) {
            _deleteCandNum = number;
            if (_line < 0) {
                _progress = PROGRESS_RETR;
                error = _pop3.SendRetrCommand(number);
            }
            else {
                _progress = PROGRESS_TOP;
                error = _pop3.SendTopCommand(number, _line);
            }
            *next = true;
        }
        else {
            *next = false;
        }
    }
    return error;
}// SFXPOP3Receiver::ReceiveNextMail //

/*private */XALLBACK_IMPLEMENT_SFXPOP3(SFXPOP3Receiver, OnPOP3Delete, error)
{
    Bool next;

    if (error == SFERR_NO_ERROR) {
        switch (_progress) {
            case PROGRESS_CONNECT:
                error = ProceedConnect();
                break;
            case PROGRESS_USER:
                error = ProceedUser();
                break;
            case PROGRESS_PASS:
                error = ProceedPass();
                break;
            case PROGRESS_LIST:
                error = ProceedList();
                break;
            case PROGRESS_UIDL:
                error = ProceedUidl(false);
                break;
            case PROGRESS_DELE:
                if (_pop3.IsResponseOk()) {
                    if ((error = DeleteNextMail(&next)) == SFERR_NO_ERROR) {
                        if (!next) {
                            _progress = PROGRESS_QUIT;
                            error = _pop3.SendQuitCommand();
                        }
                    }
                }
                else {
                    error = SFERR_FAILED;
                }
                break;
            case PROGRESS_QUIT:
                if (_pop3.IsResponseOk()) {
                    _progress = PROGRESS_DONE;
                    Finish(SFERR_NO_ERROR);
                }
                else {
                    error = SFERR_FAILED;
                }
                break;
            case PROGRESS_RETR:
            case PROGRESS_TOP:
            case PROGRESS_DONE:
            case PROGRESS_NONE:
            default:
                error = SFERR_FAILED;
                break;
        }
    }
    if (error != SFERR_NO_ERROR) {
        Finish(error);
    }
    return;
}// XALLBACK_IMPLEMENT_SFXPOP3(SFXPOP3Receiver, OnPOP3, error) //

/*private */SFCError SFXPOP3Receiver::DeleteNextMail(BoolPtr next)
{
    SFCError error(SFERR_NO_ERROR);
    SInt32 number;

    if ((number = FindNextTarget()) > -1) {
        _progress = PROGRESS_DELE;
        error = _pop3.SendDeleCommand(number);
        *next = true;
    }
    else {
        *next = false;
    }
    return error;
}// SFXPOP3Receiver::DeleteNextMail //

/*private */Void SFXPOP3Receiver::Finish(SFCError error)
{
    _state = STATE_STANDBY;
    FreeNumSizeList();
    FreeNumUidlList();
    _pop3.Close();
    if (_spp != null) {
        _spp(error, _reference);
    }
    return;
}// SFXPOP3Receiver::Finish //

/*private */SFCError SFXPOP3Receiver::SetSingleUidl(SFXAnsiStringConstRef uidl)
{
    SFCError error;
    SFXAnsiStringPtr string;

    FreeSingleUidl();
    if ((string = ::new SFXAnsiString(uidl)) != null) {
        if ((error = _singleUidlArray.InsertLast(string)) != SFERR_NO_ERROR) {
            ::delete string;
        }
    }
    else {
        error = SFERR_NO_MEMORY;
    }
    return error;
}// SFXPOP3Receiver::SetSingleUidl //

/*private */Void SFXPOP3Receiver::FreeNumSizeList(Void)
{
    if (_numSizeList != null) {
        ::delete [] _numSizeList;
        _numSizeList = null;
        _numSizeCount = 0;
    }
    return;
}// SFXPOP3Receiver::FreeNumSizeList //

/*private */Void SFXPOP3Receiver::FreeNumUidlList(Void)
{
    if (_numUidlList != null) {
        ::delete [] _numUidlList;
        _numUidlList = null;
        _numUidlCount = 0;
    }
    return;
}// SFXPOP3Receiver::FreeNumUidlList //

/*private */Void SFXPOP3Receiver::FreeSingleUidl(Void)
{
    UidlArray::Iterator itor;

    if (!_singleUidlArray.IsEmpty()) {
        itor = _singleUidlArray.GetFirstIterator();
        while (itor.HasNext()) {
            ::delete itor.GetNext();
        }
        _singleUidlArray.Clear();
    }
    return;
}// SFXPOP3Receiver::FreeSingleUidl //

/*private */Bool SFXPOP3Receiver::IsTargetUidl(SFXAnsiStringConstRef uidl)
{
    Bool result(false);
    SInt32 r0;

    if (_targetUidlArray == null) {
        result = true;
    }
    else {
        for (r0 = 0; r0 < _targetUidlArray->GetSize(); ++r0) {
            if (_targetUidlArray->Get(r0)->Equals(uidl)) {
                break;
            }
        }
        result = (r0 < _targetUidlArray->GetSize());
        if (_invertTarget) {
            result = !result;
        }
    }
    return result;
}// SFXPOP3Receiver::IsTargetUidl //

/*private */SInt32 SFXPOP3Receiver::FindNextTarget(Void)
{
    SInt32 result(-1);
    UInt32 number;
    UInt32 size;
    SInt32 r0;

    if (_noUidl) {
        if (_numSizeIndex < _numSizeCount) {
            _nextMailInfo.size = _numSizeList[_numSizeIndex].size;
            _nextMailInfo.uidl.Clear();
            _nextMailInfo.mail.Clear();
            ++_numSizeIndex;
            result = _numSizeIndex;
        }
    }
    else {
        for (; _numSizeIndex < _numSizeCount; ++_numSizeIndex) {
            number = _numSizeList[_numSizeIndex].number;
            size = _numSizeList[_numSizeIndex].size;
            for (r0 = 0; r0 < _numUidlCount; ++r0) {
                if (_numUidlList[r0].number == number) {
                    if (IsTargetUidl(_numUidlList[r0].uidl)) {
                        _nextMailInfo.size = size;
                        _nextMailInfo.uidl = _numUidlList[r0].uidl;
                        _nextMailInfo.mail.Clear();
                        ++_numSizeIndex;
                        result = number;
                        break;
                    }
                }
            }
            if (result > -1) {
                break;
            }
        }
    }
    return result;
}// SFXPOP3Receiver::FindNextTarget //

/*private */SFCError SFXPOP3Receiver::SendAuthCommand(Void)
{
    SFCError error(SFERR_NO_ERROR);
    SFXAnsiString challenge;
    SInt32 start, end;

    switch (_auth) {
        case AUTH_APOP_AND_USERPASS:
        case AUTH_ONLY_APOP:
            _apop = true;
            _progress = PROGRESS_PASS;
            if ((error = challenge.Set(_pop3.GetResponseText())) == SFERR_NO_ERROR) {
                if ((start = challenge.FirstIndexOf('<')) >= 0) {
                    if ((end = challenge.LastIndexOf('>')) >= 0) {
                        error = _pop3.SendApopCommand(_user, _password, challenge.Substring(start, end));
                    }
                    else {
                        error = SFERR_FAILED;
                    }
                }
                else {
                    error = SFERR_FAILED;
                }
            }
            break;
        case AUTH_ONLY_USERPASS:
            _progress = PROGRESS_USER;
            error = _pop3.SendUserCommand(_user);
            break;
        case AUTH_NONE:
        default:
            break;
    }
    return error;
}// SFXPOP3Receiver::SendAuthCommand //

Reference

SFXPOP3Receiver | Mail Receiving | RFC1939(Post Office Protocol - Version 3)

Member

Constructor/Destructor
SFXPOP3( `Void` ) Constructor of the SFXPOP3 class,
~SFXPOP3( `Void` ) Destructor of the 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 ) Get the response of LIST command.
`SFCError`	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 ) Get the response to the RETR command.
`SFCError`	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 the STAT command.
`SFCError`	GetTopResponse( `ACharConstHandle` response ) Get the response to the TOP command.
`SFCError`	GetTopResponse( `SFXAnsiStringPtr` response ) Get the response to the TOP command.
`UInt32`	GetTrustMode( `Void` ) Get the SSL trust mode.
`SFCError`	GetUidlResponse( `NumberUidlRecHandle` recHandle , `SInt32Ptr` recCount ) Get the response to the UIDL command.
`SFCError`	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 ) Send the POP3 command.
`SFCError`	SendCommand( `SFXAnsiStringConstRef` command , `Bool` multiline ) Send the POP3 command.
`SFCError`	SendDeleCommand( `SInt32` number ) Send the DELE command.
`SFCError`	SendListCommand( `Void` ) Send the LIST command.
`SFCError`	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` ) Send the UIDL command.
`SFCError`	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 Type that represents the callback function specified in the SFXPOP3::Connect function.
NumberSizeRec Structure to store the return value of the SFXPOP3::GetListResponse function.
NumberUidlRec Structure to store the return value of the SFXPOP3::GetUidlResponse function.

SFXPOP3::SFXPOP3

Constructor of the SFXPOP3 class,

[ public, explicit ]
SFXPOP3(Void);

Description

This constructor turns the SSL connection mode off.

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

Reference

SFXPOP3::SetSSLMode | SFXPOP3::Open

SFXPOP3::~SFXPOP3

Destructor of the SFXPOP3 class.

[ public, virtual ]
~SFXPOP3(Void);

Description

This destructor closes the POP3 connection.

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

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

If succeeds: 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 the BREW API ISOCKET_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::CallbackSPP | BREW API ISOCKET_GetLastError

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

If succeeds: 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::Connect | RFC1939: 5. The TRANSACTION State

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

If succeeds: SFERR_NO_ERROR
If connection has not been established: SFERR_INVALID_STATE
If the result argument is null: SFERR_INVALID_PARAM
For other network errors: get error value by the BREW API ISOCKET_GetLastError function.

Description

This function gets the local IP address and port number of the internal socket.

Reference

SFXInetAddress::LocalInetAddress | SFXTCPSocket::GetLocalAddress | BREW API ISOCKET_GetLastError

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

If succeeds: SFERR_NO_ERROR
If connection has not been established: SFERR_INVALID_STATE
If the result argument is null: SFERR_INVALID_PARAM
For other network errors: get error value by the BREW API ISOCKET_GetLastError function.

Description

This function gets the remote IP address and port number of the peer connected by the internal socket.

Reference

SFXTCPSocket::GetRemoteAddress | BREW API ISOCKET_GetLastError

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.

Return value

Response buffer

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::Connect | SFXPOP3::Close | RFC1939: 3. Basic Operation

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

If succeeds: SFERR_NO_ERROR
If connection has not been established: SFERR_INVALID_STATE
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::Connect | RFC1939: 3. Basic Operation

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

If succeeds: SFERR_NO_ERROR
If the response argument is null: 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 | RFC1939: 5. The TRANSACTION State

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 the 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

If succeeds: SFERR_NO_ERROR
If connection has not been established, or the status immediately before POP3 command is not "+OK": SFERR_INVALID_STATE

Description

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

Reference

SFXPOP3::SendStatCommand | RFC1939: 5. The TRANSACTION State

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

If succeeds: SFERR_NO_ERROR
If the response argument is null: 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 top part of the mail message.

Reference

SFXPOP3::SendTopCommand | SFXPOP3::GetRetrResponse | RFC1939: 7. Optional POP3 Commands

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

Reference

SFXPOP3::SetTrustMode | BREW API ISSL_NegotiateV

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

If succeeds: 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 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 | RFC1939: 7. Optional POP3 Commands

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::GetResponseBuffer | SFXPOP3::IsResponseOk | RFC1939: 3. Basic Operation

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::GetResponseBuffer | SFXPOP3::IsResponseErr | RFC1939: 3. Basic Operation

SFXPOP3::Open

Perform the initialization for connecting to the POP3 server.

[ public ]
SFCError Open(Void);

Return value

If succeeds: 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

The SFXSSLSocket::Open function is called internally in this function. When the TCP connection is used, the SFXSSLSocket::Permit function will be called in the internal callback function of the SFXPOP3::Connect function.

Reference

SFXSSLSocket::Open | SFXSSLSocket::Permit | SFXPOP3::Connect | 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

If succeeds: SFERR_NO_ERROR
If connection has not been established: SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY

Description

The APOP command is for the APOP authentication.

Call this 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 | RFC1939: 7. Optional POP3 Commands

SFXPOP3::SendCommand

Send the POP3 command.

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

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

Return value

If succeeds: SFERR_NO_ERROR
If invalid argument: SFERR_INVALID_PARAM
If connection has not been established: SFERR_INVALID_STATE
If failed: SFERR_FAILED

Description

"\r\n" needs to be added at the end of the POP3 command. Whether the 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

If succeeds: SFERR_NO_ERROR
If connection has not been established: SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY

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::SendQuitCommand SFXPOP3::Connect | RFC1939: 5. The TRANSACTION State

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

If succeeds: SFERR_NO_ERROR
If connection has not been established: SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY

Description

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

To get the size of all the mail messages, call this 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 | RFC1939: 5. The TRANSACTION State

SFXPOP3::SendNoopCommand

Send the NOOP command.

[ public ]
SFCError SendNoopCommand(Void);

Return value

If succeeds: SFERR_NO_ERROR
If connection has not been established: SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY

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 | RFC1939: 5. The TRANSACTION State

SFXPOP3::SendPassCommand

Send the PASS command.

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

Argument

password: Specify a password.

Return value

If succeeds: SFERR_NO_ERROR
If connection has not been established: SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY

Description

The PASS command is the command to set a password.

This 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 | RFC1939: 7. Optional POP3 Commands

SFXPOP3::SendQuitCommand

Send the QUIT command.

[ public ]
SFCError SendQuitCommand(Void);

Return value

If succeeds: SFERR_NO_ERROR
If connection has not been established: SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY

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

If succeeds: SFERR_NO_ERROR
If connection has not been established: SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY

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 | RFC1939: 5. The TRANSACTION State

SFXPOP3::SendRsetCommand

Send the RSET command.

[ public ]
SFCError SendRsetCommand(Void);

Return value

If succeeds: SFERR_NO_ERROR
If connection has not been established: SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY

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 | RFC1939: 5. The TRANSACTION State

SFXPOP3::SendStatCommand

Send the STAT command.

[ public ]
SFCError SendStatCommand(Void);

Return value

If succeeds: SFERR_NO_ERROR
If connection has not been established: SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY

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 | RFC1939: 5. The TRANSACTION State

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

If succeeds: SFERR_NO_ERROR
If connection has not been established: SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY

Description

The TOP command is the command to get the specified top part 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 | RFC1939: 7. Optional POP3 Commands

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

If succeeds: SFERR_NO_ERROR
If connection has not been established: SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY

Description

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

To get all the UIDLs of the mail messages, call this 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 | RFC1939: 7. Optional POP3 Commands

SFXPOP3::SendUserCommand

Send the USER command.

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

Argument

user: Specify a username.

Return value

If succeeds: SFERR_NO_ERROR
If connection has not been established: SFERR_INVALID_STATE
If insufficient memory: SFERR_NO_MEMORY

Description

The USER command is the command to set a username.

This 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 | RFC1939: 7. Optional POP3 Commands

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, specify true in the "isSSL" argument.

Reference

SFXPOP3::GetSSLMode | SFXPOP3::SFXPOP3

SFXPOP3::SetTrustMode

Set the SSL trust mode.

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

Return value

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

Reference

SFXPOP3::GetTrustMode | SFXPOP3::Connect | SFXSSLSocket::SetTrustMode | BREW API ISSL_NegotiateV

SFXPOP3::CallbackSPP

Type that represents the callback function specified in the SFXPOP3::Connect 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.

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.

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 return value 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 return value 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 return value 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 return value 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