protolib(3)

SYNOPSIS
#include <proto.h>
int init(char *name, Tcl_Interp *interp);
int next_proto(struct packet *pckt, int element, char **name,
    int *next_offset);
int propen(ClientData clientData, Tcl_Interp *interp,
    int argc, char *argv[]);
int prclose(ClientData clientData, Tcl_Interp *interp,
    int argc, char *argv[]);
int pinit(ClientData clientData, Tcl_Interp *interp,
    struct packet *pckt, int argc, char *argv[]);
int pfree(ClientData clientData, Tcl_Interp *interp,
    struct packet *pckt, int argc, char *argv[]);
int get(int element, ClientData clientData, Tcl_Interp *interp,
    struct packet *pckt, int argc, char *argv[]);
int set(int element, ClientData clientData, Tcl_Interp *interp,
    struct packet *pckt, int argc, char *argv[]);
int list(int element, ClientData clientData, Tcl_Interp *interp,
    struct packet *pckt, int argc, char *argv[]);

DESCRIPTION

The packet shell protocol libraries are provided by supplying the interfaces listed above. Although a particular protocol might not supply any particular items above, the next_proto() routine is required.

If provided, the init() routine is called as soon as the protocol is linked with the packet shell. This allows the protocol library to do any initialization desired. The name is the protocol's name. Note that the protocol library's file name is presumed to be its name, and is passed in. The library should take care to use that name when describing itself or its actions, not a compiled-in name.

The next_proto is required to identify what protocol this layer is encapsulated. For example, the IP library's next_proto() must identify when the payload is a TCP packet, and return the protocol name. The element argument indicates which offset into the packet table represents this protocol's segment. So if element is 2, and this is the IP library, then pckt->ptbl[2].name points at "ip". The name argument must be set to the name of the next protocol. The pointer should be to memory statically allocated if possible, since no free() operation is possible on this pointer when the packet table changes. The next_proto() routine returns logical true, unless it is the end of the packet, in which case it must return false.

Next_offset must be set to the the offset, from the beginning of the packet buffer, of the next protocol layer. If the next protocol layer is unknown, or unstructured, the protocol name should be designated as the special protocol "data". If this is the last layer in the packet, next_offset must be set to the offset of the end of the packet, and the protocol name must be set the special value "end".

All other entry points are call-outs from TCL commands. They return values using Tcl_ReturnResult().

Pinit() and pfree() initialize and free a packet. Upon entry argv[0] is the packet variable name. If additional arguments are present the protocol may interpret them as it wishes. By convention, the first argument is the length of the total buffer space to allocate for the packet.

The get() routine returns various protocol elements. Upon entry element indicates which protocol table element describes the section of the packet the protocol layer is stored. Argv[0] is the name of the protocol element.

Set() command works similarly to get() except that it is for setting values instead of fetching values. List() is in the same spirit, but returns a summary.

Propen() and prclose() open and close a communication end-point. Argv[0] is the name of the end-point. Note that each protocol has its own end-point name-space. Each protocol is also responsible for tracking the names, the open file descriptors, and so on for its end-points.

All functions should be declared static, unless they are one of the entry points.

OTHER INTERFACES

The packet shell also exports a integer called seconds_bias which is the "origin" for packet arrival times stored in the p_at element of the struct packet structure. This may be of interest to protocol libraries if they wish to compute absolute time and date of a packet's arrival. The value store in p_at is a struct timeval tv_sec value.

SEE ALSO

psh(1), xpsh(1).