Hamster-Scripts: Functions (built-in)

Messages (Usenet/Mail)

MsgAlloc( <Text> )

MsgAlloc

Creates a new message and returns a unique handle for it. This handle is noted as <msg> in the other Msg-functions described below and is valid until the message is freed again by "MsgFree".

If <text> is given, the message is initialized with it, else it is empty.

Returns: message-handle

$msg = MsgAlloc

MsgFree( <msg> )

Frees a message created by "MsgAlloc".

Returns: 0: OK, -1: invalid message-handle

MsgFree( $msg )

MsgLoad( <msg>, <filename> )

Loads full message text from the given text file and assigns it to message.

Returns: 0: OK, -1: file not found, -2: error

MsgLoad( $msg, HamMailsOutPath + "42.msg" )

MsgSave( <msg>, <filename> )

Saves full message text of message in the given text file.

Returns: 0: OK, -2: error

MsgSave( $msg, HamMailsOutPath + "42.msg" )

MsgGetText( <msg> )

MsgGetHeaders( <msg> )

MsgGetBody( <msg> )

Returns a CR/LF-separated text containing the full message text, all header lines only or all body lines only.

Returns: String

$Text = MsgGetText( $msg )
$Hdrs = MsgGetHeaders( $msg )
$Body = MsgGetBody( $msg )

MsgSetText( <msg>, <text> )

MsgSetHeaders( <msg>, <headers> )

MsgSetBody( <msg>, <body> )

Sets full message text, all header lines only or all body lines only from the CR+LF separated <text>.

Returns: 0: OK, -1: invalid message-handle

MsgSetText( $msg, $Text )
MsgSetHeaders( $msg, $Headers )
MsgSetBody( $msg, $Body )

MsgGetHeader( <msg>, <hdrnam>, <separate> )

MsgGetHeader( <msg>, <hdrnam> )

Get the value of the header line named <hdrnam>, empty string if not found.
If header has continuation lines, the values of these lines are either appended to the result, each separated by a single space (<separate>=false, 0 or missing), or are returned "as they are", i. e. with CR+LF separators and indentation left intact (<separate>=true or <>0).

Returns: String

$Subject = MsgGetHeader( $msg, "Subject" )

MsgAddHeader( <msg>, <hdrnam>, <hdrval> )

Add a header with given name and value, even if there's already one with the given name. <hdrval> may also contain continuation lines separated by CRLF and indented appropriate.

Returns: 0=OK

MsgAddHeader( $msg, "Subject", "This is the subject!" )

MsgSetHeader( <msg>, <hdrnam>, <hdrval>, <xhdrnam> )

MsgSetHeader( <msg>, <hdrnam>, <hdrval> )

Like MsgAddHeader, but also removes an already existing header with the given name. If <xhdrnam> is given, the value of such a removed header is saved under the name given here.

Returns: 0=OK

MsgSetHeader( $msg, "Subject", "This is the new subject!", "X-Old-Subject" )

MsgDelHeader( <msg>, <hdrnam> )

Removes the given header line.

Returns: 0=OK

MsgDelHeader( $msg, "X-Old-Subject" )

MsgHeaderExists( <msg>, <hdrnam> )

Checks, if message contains the given header line.

Returns: 0=false=no, 1=true=yes

if( MsgHeaderExists( $msg, "X-Old-Subject" ) )

[www.elbiah.de Hamster Playground Documentation]