Error	Value	Definition
NSMAIL_OK	0	Successful completion of function.
NSMAIL_ERR_UNINTIALIZED	-1	Uninitialized value.
NSMAIL_ERR_INVALIDPARAM	-2	Invalid parameters.
NSMAIL_ERR_OUTOFMEMORY	-3	Out of memory.
NSMAIL_ERR_UNEXPECTED	-4	Unexpected element.
NSMAIL_ERR_IO	-5	Error in input/output operation.
NSMAIL_ERR_IO_READ	-6	Error in reading input stream.
NSMAIL_ERR_IO_WRITE	-7	Error in writing to output stream.
NSMAIL_ERR_IO_SOCKET	-8	Socket connection error.
NSMAIL_ERR_IO_SELECT	-9	Error in selecting message.
NSMAIL_ERR_IO_CONNECT	-10	Error in connecting.
NSMAIL_ERR_IO_CLOSE	-11	Error in closing.
NSMAIL_ERR_PARSE	-12	Internal parsing error occurred.
NSMAIL_ERR_TIMEOUT	-13	Timeout occurred. Recoverable error. Wait and call `processResponses` later.
NSMAIL_ERR_INVALID_INDEX	-14	Index is invalid.
NSMAIL_ERR_CANTOPENFILE	-15	Cannot open file.
NSMAIL_ERR_CANT_SET	-16	Value cannot be set.
NSMAIL_ERR_ALREADY_SET	-17	Value already set.
NSMAIL_ERR_CANT_DELETE	-18	Cannot delete item.
NSMAIL_ERR_CANT_ADD	-19	Cannot add item.
NSMAIL_ERR_SENDDATA	-20	Data send failed. Recoverable error.
NSMAIL_ERR_MUSTPROCESSRESPONSES	-21	Response not processed. Recoverable error.
NSMAIL_ERR_ PIPELININGNOTSUPPORTED	-22	Server does not support pipelining. Recoverable error.
NSMAIL_ERR_ALREADYCONNECTEDD	-23	Already connected.
NSMAIL_ERR_NOTCONNECTED	-24	Not connected.
NSMAIL_ERR_EOF	-1	End of file reached.
NSMAIL_ERR_NOTIMPL	-99	Function or feature not implemented.

[Top] [Shared Definitions]

Shared Structures

This section defines Messaging Access SDK data structures, listed in alphabetical order. These structures represent input and output streams used by the SDK Protocol APIs.

nsmail_io_fns_t

nsmail_inputstream_t

nsmail_outputstream_t

[Top]

nsmail_io_fns_t

Definition for a structure to plug in specific IO functionality.

Syntax

include <nsmail.h> 
typedef struct nsmail_io_fns 
{ 
   int (*liof_read)(int, char *, int); 
   int (*liof_write)(int, char *, int); 
   int (*liof_socket)(int, int, int);
   int (*liof_select)(int, fd_set *, 
            fd_set *, fd_set *, struct timeval *); 
   int (*liof_connect)(int, 
            const struct sockaddr*, int); 
   int (*liof_close)(int); 
} nsmail_io_fns_t;

Fields

The structure has the following fields:

int (liof_read)(int, char , int);	Reads data.
int (liof_write)(int, char , int);	Writes data.
int (*liof_socket)(int, int, int);	Creates the socket handle.
int (liof_select)(int, fd_set , fd_set , fd_set , struct timeval *);	Selects.
int (liof_connect)(int, const struct sockaddr, int);	Eastablishes a connection.
int (*liof_close)(int);	Closes the connection.

Description

This structure is made up of pointers to the standard functions supported on most platforms. In order to plug in specific input and output functionality, the developer must define these functions.

nsmail_inputstream_t

Definition for a structure to plug in specific input streaming functionality.

Syntax

include <nsmail.h> 
typedef struct nsmail_inputstream 

   void *rock; 
   int (*read) (void *rock, 
            char *buf, unsigned size); 
   void (*rewind) (void *rock);
   void (*close) (void *rock);
} nsmail_inputstream_t;

Fields

The structure has the following fields:

void *rock	Opaque client data.
int (read) ( void rock, char *buf, unsigned size);	Returns the number of bytes actually read and -1 on eof on the stream; may return an `NSMAIL_ERR* (int value < 0)` in case of any other error. Can be invoked multiple times. Each read returns the next sequence of bytes in the stream, starting after the last byte returned by the previous read. If the number of bytes actually returned by read is less than `size` parameter, an eof on the stream is assumed. Parameters: `buf`: space allocated and freed by the caller. `size:` maximum number of bytes to be returned by read. If the number of bytes returned by read is less than `size`, an eof on the stream is assumed.
void (rewind) (void rock);	Reset the stream to the beginning. A subsequent read returns data from the start of the stream.
void (close) (void rock);	Closes the stream, freeing any internal buffers and `rock` parameter. Once a stream is closed, it is illegal to attempt `read`, `rewind`, or `close` on the stream. After `close`, the user of the stream must free the `nsmail_inputstream` structure corresponding to the stream.

Description

This structure is made up of pointers to functions. The developer must define these functions.

nsmail_outputstream_t

Definition for a structure to plug in specific output streaming functionality.

Syntax

include <nsmail.h> 
typedef struct nsmail_outputstream 
{ 
   void *rock; 
   void (*write) (void *rock, const char *buf, 
            unsigned size);
   void (*close) (void *rock);
} nsmail_outputstream_t;

Fields

The structure has the following fields:

void *rock;	Opaque client data.
void (write) (void rock, const char *buf, unsigned size);	Writes CRLF-separated output in `buf` parameter, of size `size`. May be called multiple times.
void (close) (void rock);	Closes the stream, freeing any internal buffers, rock, and other data. After a stream is closed, it is illegal to attempt `write` or `close` operations on the stream. After `close`, the user of the stream must free the `nsmail_outputstream` structure corresponding to the stream.

Description

This structure is made up of pointers to functions. The developer must define these functions.

Shared Functions

The Messaging Access SDK defines several functions that create input and output streams used by the SDK Protocol APIs.

file_inputStream_create

buf_inputStream_create

file_outputStream_create

nsStream_free

To use the functions declared by this header file, link with the libcomm.so file.

[Top]

file_inputStream_create

Creates an input stream from a file.

Syntax

#include <nsStream.h> 
int file_inputStream_create (char * in_fileName, 
         nsmail_inputstream_t ** out_ppRetInputStream);

Parameters

The function has the following parameters:

in_fileName	Full path name of an existing file on which to create the input stream.
out_ppRetInputStream	The created input stream is returned here.

nsmail_inputstream_t * pInputStream;

ret_value = file_inputStream_create (
            <file-name>, &pInputStream);

ret_value = mime_basicPart_setDataStream (
            BasicPart, pInputStream, boolean);

/* When done, close and free the stream. */

pInputStream->close (pInputStream->rock);

free (pInputStream); pInputStream = NULL;

[Top] [Shared Functions]

buf_inputStream_create

Creates an input stream from a buffer.

Syntax

#include <nsStream.h> 
int buf_inputStream_create (
            char * in_pDataBuf, 
            long in_data_size, 
            nsmail_inputstream_t ** out_ppRetInputStream);

Parameters

The function has the following parameters:

in_pDataBuf

Data buffer on which to base the input stream. Should not be null. A reference to the buffer is stored in the stream.

Do not free the buffer until the stream is closed.

in_data_size

Size of data in in_pDataBuf.

out_ppRetInputStream

The created input stream is returned here.

Returns

If successful, the function returns NSMAIL_OK (0).

If unsuccessful, the function returns an error message (< 0 ). For a complete list, see Error Definitions.

Description

Example

This function is used in the same way shown in the Example for file_inputStream_create.

file_outputStream_create

Creates an input stream from a buffer.

Syntax

#include <nsStream.h> 
int file_outputStream_create (
         char * in_fileName, 
         nsmail_outputstream_t ** out_ppRetOutputStream);

Parameters

The function has the following parameters:

in_fileName	Full path name of the file on which to create the output stream. Creates the file if needed. Deletes any previous data in the file.
out_ppRetOutputStream	The created output stream is returned here.

Returns

If successful, the function returns NSMAIL_OK (0).

If unsuccessful, the function returns an error message (< 0 ). For a complete list, see Error Definitions.

Description

This function creates an output stream that can be passed to all Messaging Access SDK API calls that require a parameter of type nsmail_outputstream_t.

Example

This code shows how to use this function. The file under the stream must be removed separately.

nsmail_outputstream_t * pOutputStream;

ret_value = file_outputStream_create (<file-name>, 
               &pOutputStream);

ret_value = mime_message_putByteStream (
               <other-params>, pOutputStream);

/* When done, close and free the stream. */

pOutputStream->close (pOutputStream->rock);

nsStream_free (pOutputStream);

pOutputStream = NULL;

[Top] [Shared Functions]

nsStream_free

Frees the memory allocated for the input or output stream.

Syntax

#include <nsStream.h> 
void nsStream_free (void * pMem);

Parameters

The function has the following parameters:

pMem	Stream to free.

Returns

If successful, the function returns NSMAIL_OK (0).

If unsuccessful, the function returns an error message (< 0 ). For a complete list, see Error Definitions.

Chapter 8 Shared C Definitions

Chapter 8
Shared C Definitions