TElPOP3Client.ReceiveMessage method

TElPOP3Client.ReceiveMessage

Retrieves the message from the server

Declaration

[C#]
    void ReceiveMessage(int Index);
    int ReceiveMessage(int Index, byte[] Buffer, int Offset, int Count);
    void ReceiveMessage(int Index, System.IO.Stream Stream);
    int ReceiveMessage(int Index, string HeaderCharset, string BodyCharset, TElMessageParsingOptions Options, bool IgnoreHeaderNativeCharset, bool IgnoreBodyNativeCharset, bool ActivatePartHandlers, out TElMessage Message);

[VB.NET]
    Sub ReceiveMessage(ByVal Index As Integer)
    Function ReceiveMessage(ByVal Index As Integer, ByVal Buffer As Byte(), ByVal Offset As Integer, ByVal Count As Integer) As Integer
    Sub ReceiveMessage(ByVal Index As Integer, ByVal Stream As System.IO.Stream)
    Function ReceiveMessage(ByVal Index As Integer, ByVal HeaderCharset As String, ByVal BodyCharset As String, ByVal Options As TElMessageParsingOptions, ByVal IgnoreHeaderNativeCharset As Boolean, ByVal IgnoreBodyNativeCharset As Boolean, ByVal ActivatePartHandlers As Boolean, Out Message As TElMessage) As Integer

[Pascal]
    procedure ReceiveMessage(Index: Integer);
    function ReceiveMessage(Index: Integer; Buffer: ByteArray; Offset: Integer; Count: Integer);
    procedure ReceiveMessage(Index: Integer; Stream: TStream);
    function ReceiveMessage(Index: Integer; HeaderCharset: string; BodyCharset: string; Options: TElMessageParsingOptions; IgnoreHeaderNativeCharset: Boolean; IgnoreBodyNativeCharset: Boolean; ActivatePartHandlers: Boolean; out Message: TElMessage): Integer;

    TElMessageParsingOptions represents a bit mask which contains zero or more bit flags as defined by TElMessageParsingOption

[C++]
    void ReceiveMessage(int32_t Index);
    int32_t ReceiveMessage(int32_t Index, const std::vector<uint8_t> &Buffer, int32_t Offset, int32_t Count);
    void ReceiveMessage(int32_t Index, TStream &Stream);
    void ReceiveMessage(int32_t Index, TStream *Stream);
    int32_t ReceiveMessage(int32_t Index, const std::string &HeaderCharset, const std::string &BodyCharset, TElMessageParsingOptions Options, bool IgnoreHeaderNativeCharset, bool IgnoreBodyNativeCharset, bool ActivatePartHandlers, TElMessage &Message);

[PHP]
    void ReceiveMessage(integer $Index)
    integer ReceiveMessage(integer $Index, array of byte|string|NULL $Buffer, integer $Offset, integer $Count)
    void ReceiveMessage(integer $Index, TStream $Stream)
    integer ReceiveMessage(integer $Index, string $HeaderCharset, string $BodyCharset, integer $Options, bool $IgnoreHeaderNativeCharset, bool $IgnoreBodyNativeCharset, bool $ActivatePartHandlers, TElMessage &$Message)

[Java]
    int receiveMessage(int Index, byte[] Buffer, int Offset, int Count);
    int receiveMessage(int Index, String HeaderCharset, String BodyCharset, TElMessageParsingOptions Options, boolean IgnoreHeaderNativeCharset, boolean IgnoreBodyNativeCharset, boolean ActivatePartHandlers, TSBObject MessageRef);
    void receiveMessage(int Index);
    void receiveMessage(int Index, TElStream Stream);

Parameters

Index - index of the message to receive
Buffer - buffer to which the message should be placed
Offset - position in the buffer where to start writing the data to
Count - number of bytes in buffer available for writing
Stream - the stream to save the message to
HeaderCharset - charset of the header
BodyCharset - charset of the body
Options - parsing options (see below)
IgnoreHeaderNativeCharset - specifies what charset must be applied to the message header.
True - the one specified in HeaderCharset
False - the one specified in the message (if present) or specified in HeaderCharset if there is no charset specified in the message.
IgnoreBodyNativeCharset - specifies what charset must be applied to the message body.
True - the one specified in BodyCharset
False - the one specified in the message (if present) or specified in BodyCharset if there is no charset specified in the message.
ActivatePartHandlers - specifies if handlers must be invoked automatically.
True - if there is a handler found for the part it will be invoked automatically during part processing.
False - even if handler is found it won't be invoked automatically.
Message - on return contains a created reference to the parsed message.
MessageRef -

Return value

The overloaded method which reads the data into the buffer returns the number of bytes copied to the buffer.
The overloaded method which parses the message returns 0 (EL_OK) on success, 1 (EL_WARNING) if source data contains byte sequences illegal for given charsets and error code in other cases.

TELMessageParsingOptions values

[.NET]	[Pascal]	[C++]	Description
mpoStoreStream = 1	mpoStoreStream	f_mpoStoreStream = 1	Stores positions of the message parts in internal structure. Allows to decipher message and check signature.
mpoLoadData = 2	mpoLoadData	f_mpoLoadData = 2	Specifies if message body will be loaded into internal storage.
mpoCalcDataSize = 4	mpoCalcDataSize	f_mpoCalcDataSize = 4	Specifies if real message size will be calculated.
mpoRaiseError = 8	mpoRaiseError	f_mpoRaiseError = 8	Specifies whether to raise an exception when an error occurrs during parsing.
mpoDelayDataDecode = 16	mpoDelayDataDecode	f_mpoDelayDataDecode = 16	Defines that the data is not decoded during parsing (if it was encoded). Parsing will be faster, but first data retrieval will be slower, when this option is set.

TElMessageParsingOptions values

[.NET][C++]	[Pascal]	[PHP]	Description
f_mpoStoreStream = 1	mpoStoreStream	mpoStoreStream = 1	Stores positions of the message parts in internal structure. Allows to decipher message and check signature.
f_mpoLoadData = 2	mpoLoadData	mpoLoadData = 2	Specifies if message body will be loaded into internal storage.
f_mpoCalcDataSize = 4	mpoCalcDataSize	mpoCalcDataSize = 4	Specifies if real message size will be calculated.
f_mpoRaiseError = 8	mpoRaiseError	mpoRaiseError = 8	Specifies whether to raise an exception when an error occurrs during parsing.
f_mpoDelayDataDecode = 16	mpoDelayDataDecode	mpoDelayDataDecode = 16	Defines that the data is not decoded during parsing (if it was encoded). Parsing will be faster, but first data retrieval will be slower, when this option is set.

Description

Call this method to retrieve the message from the server and optionally parse it.

The simplest method overload (which has only Index as a parameter) passes message data via OnMessageLine event. Other overloads eiter let you provide a memory buffer or Stream/TStream object or parse a message for you.

Note, Options setting differs for VCL and .NET versions. To enable several options in .NET use bitwise OR operation, for example "mpoStoreStream | mpoLoadData | mpoCalcDataSize".

Discuss this help topic in SecureBlackbox Forum