Access a stored message for reading.

int POPSTORE_message_begin (user_context, message_index, message_context, env_id, env_id_len msg_id, msg_id_len) POPSTORE_user_context *user_context; int message_index; int *message_context; char *env_id; int *env_id_len; char *msg_id; int *msg_id_len;

Arguments

user_context

User context created by a previous call to POPSTORE_user_begin_d. Used for input only.

message_index

Index of the message to access. Used for input only.

message_context

Message context established by this call. Dispose of the context by calling POPSTORE_message_end. Used for output only.

env_id

Pointer to a string in which to return the value of the message's envelope identification field. Used for output only.

env_id_len

On input, the maximum length in bytes of the buffer to receive the message's envelope identification field, env_id. On output, the length in bytes of the returned envelope identification field. Used for input and output.

msg_id

Pointer to a string in which to return the value of the message's message identification field. Used for output only.

msg_id_len

On input, the maximum length in bytes of the buffer to receive the message identification field, msg_id. On output, the length in bytes of the returned message identification field. Used for input and output.

Description

To access a user's nth message for purposes of reading it, call POPSTORE_message_begin with message_index set to the value n. (The first message has index 1, the second index 2, and so on.) The message context returned can then be used with POPSTORE_message_read to read the message. When done reading the message, call POPSTORE_message_end to close the message file and end the context. Optionally, the values of the message's envelope and message identification fields can be returned. To receive the value for the envelope identification, supply with env_id the address of a buffer to receive the value. On input, env_id_len should point to an integer whose value is the maximum size in bytes of that buffer. On output, the value of that integer will be changed to be the length in bytes of the returned envelope identification field. The same holds for the message identification field. To be ensured that that entire field values are returned and not truncated, the buffers should have lengths of at least ALAFA_SIZE bytes plus an additional byte to store a null terminator. If you are not interested in obtaining the envelope identification, you can pass a null value for env_id. Likewise for the message identification. Note that if site-supplied logging subroutines are in use, the envelope identification for the message will not be logged when you supply a null value for env_id. Again, likewise for the message identification. An example of using POPSTORE_message_begin is given in Example 12-8.

Return Values

POPSTORE_SUCCESS	Normal, successful completion.
POPSTORE_BADMSG	Underlying message file is corrupted or otherwise unreadable; message marked for deletion.
POPSTORE_BADMSGID	Message index is less than 1 or greater than user_context->message_count.
POPSTORE_DELETED	Message has been marked for deletion.
POPSTORE_FILOPNERR	Unable to open the underlying message file.
POPSTORE_NULLCONTEXT	user_context context is null.
POPSTORE_NULLMSGLIST	user_context->messages is null.
POPSTORE_NULLPROFILE	user_context->profile context is null.
POPSTORE_TOOLONG	File specification for the underlying message file is too long.