The Transfer Agent

SMT
Version 2.81

The Transfer Agent - SMTTRAN

Transfers blocks of data or files to connected sockets. You can use this agent to simplify certain types of communication. The transfer agent uses the socket agent for actual reading and writing to sockets.

To use SMTTRAN, call smttran init(). This creates a single unnamed thread automatically the first time it is called, and has no effect thereafter. You can then send messages to this thread. It supports these methods:

PUT_BLOCK - writes a length-specified block to a socket.
GET_BLOCK - reads a length-specified block from a socket.
PUT_FILE - writes an entire file to a socket.
GET_FILE - reads an entire file from a socket.
COMMIT - wait until all outstanding requests are complete.

Example of initialising SMTTRAN:

/*  Static data                                                 */
static QID
    tranq;                      /*  Transfer agent queue        */

    /*  In agent initialisation code                            */
    THREAD  *thread;            /*  Handle to console thread    */
    /*  Ensure that transfer agent is running, else start it    */
    smttran init ();
    if ((thread = thread lookup (SMT_TRANSFER, "")) != NULL)
        tranq = thread-> queue-> qid;
    else
        return (-1);

The PUT_BLOCK Method

Writes a length-specified block to a socket: first writes a two-byte length specifier in network format, then writes the block data. Build the event body using exdr_write() and the message definition SMT_TRAN_PUTB. The event body consists of these fields (see exdr_write() for the field types):

[q] socket to use for output.
[mM] block of data to write to socket.

SMTTRAN replies to a PUT_BLOCK event with one of these events:

TRAN_PUT_OK - the block was completely written to the socket. The event body contains the amount of data written. Decode the event body, if you need to, using exdr_read() and the message definition SMT_TRAN_PUTB_OK. The body contains these fields: [d] the size of the block.
TRAN_CLOSED - the socket was closed before the block could be completely written. The event body is empty.
TRAN_ERROR - there was an error on the socket. The event body contains the socket error message text.

The GET_BLOCK Method

Reads a length-specified block from a socket: first reads a two-byte length specifier in network format, then reads that many bytes of block data. Build the event body using exdr_write() and the message definition SMT_TRAN_GETB. The event body consists of these fields (see exdr_write() for the field types):

[q] socket to use for input.

SMTTRAN replies to a GET_BLOCK event with one of these events:

TRAN_GET_OK - the block was completely read from the socket. The event body contains the data block. Decode the event body using exdr_read() and the message definition SMT_TRAN_GETB_OK. The body contains these fields: [mM] the data block.
TRAN_CLOSED - the socket was closed before the block could be completely read. The event body is empty.
TRAN_ERROR - there was an error on the socket. The event body contains the socket error message text.

The PUT_FILE Method

Writes a file to a socket: reads the file in pieces of unspecified size, and writes these to the output socket. Build the event body using exdr_write() and the message definition SMT_TRAN_PUTF. The event body consists of these fields (see exdr_write() for the field types):

[q] socket to use for output.
[s] name of file to write to socket.

SMTTRAN replies to a PUT_FILE event with one of these events:

TRAN_PUT_OK - the file was completely written to the socket. The event body contains the amount of data written. Decode the event body, if you need to, using exdr_read() and the message definition SMT_TRAN_PUTF_OK. The body contains these fields: [q] the size of the file.
TRAN_CLOSED - the socket was closed before the file could be completely written. The event body is empty.
TRAN_ERROR - there was an error on the socket or accessing the file. The event body contains the socket or file error message text.

The GET_FILE Method

Reads a file from a socket and saves it with the specified name. Build the event body using exdr_write() and the message definition SMT_TRAN_GETF. The event body consists of these fields (see exdr_write() for the field types):

[q] socket to use for input.
[s] name of file to create.

SMTTRAN replies to a GET_FILE event with one of these events:

TRAN_GET_OK - the file was completely read from the socket. The event body contains the amount of data written. Decode the event body, if you need to, using exdr_read() and the message definition SMT_TRAN_GETF_OK. The body contains these fields: [q] the size of the file.
TRAN_CLOSED - the socket was closed before the file could be completely read. The event body is empty.
TRAN_ERROR - there was an error on the socket or accessing the file. The event body contains the socket or file error message text.

The COMMIT Method

Waits until all put and get requests are finished, then replies with a TRAN_CLOSED event. This event does not take any arguments. SMTTRAN replies to a GET_FILE event with one of these events:

TRAN_CLOSED - no requests remain. The event body is empty.
TRAN_ERROR - there was an error on the socket. The event body contains the socket error message text.

Example Of Use

The SMTHTTP agent uses the transfer agent to send files.

SMTTRAN Implementation

The hypertext view of SMTTRAN's dialog and source code may help to understand how SMTTRAN works.

| << | < | > | >>