External Agent Interface Implementation

Document formatted by vherva at Fri Apr 24 11:23:39 1998 on the host schemestation. This document is produced by the SchemeStation project during the Tik-76.115 course.

1 Introduction
	The external agent interface described in External Agent Interface Specification has some similarities with the networking system (Networking Specification). The implementation has also some similarities. The server listen to a specified port, accepts connections, and passes the fd's to the event loop. The event loop then wakes a specified function to manage reads and writes from this fd. The external agent system also inceludes a separate library that the clients may use to connect to the server.
2 Addressing
	In the addressing system, there is a special type for external agents. When the messaging system receives a message to be patches and find out from the addressing system, that the destination of the message is an external agent, it passes it to the extarnal agent system instead of the networking system. The addressing system entry contains the fd of the corresponding client connection, so that the mapping in the external agent is rather straightforward. As said in External Agent Interface Specification, neither the server nor the client is aware of the agent specifiers when in comes to sending a packet to a native agent. Instead, the interface agent dispatches the packets sent by the client, and passes them further to the native agents. (Naturally, it may also decide not pass the packet anywhere.)
3 The server
	When a domain is started, the listened port is bound and begun to listen with extag_initialize(). The port number is passed as a command line argument. If listening the port fails, the function returns error. When the messaging system requests the external agent system to pass a packet to a cient, it specifies the client with the fd of the connection. The external agent system then searches its list of readily established connection if there is one with that fd. If such one is found, it then puts the packet on the connection's list of packets to be send with extag_deliverpacket. The event loop notifies external agent module every time it is possibly to send to a connection by calling extag_eloop_callback. The external agent module then sends as many packets as possible with extag_sendpacket and gives the control back to the caller. The event loop also notifies the external agent module of arrived packets by calling extag_eloop_callback. The external agent system reads all available packets from the socket with extag_recvpacket and for every completely received packet it calls the addressing systems callback registered with extag_registerpacketcallback. Packets can be partially received or sent, in which case they are completed when the event loop gives controls back next time. Opening a connection in the erver side consists of calling extag_acceptconnection that allocates the connection struct, adds it to the global connection list, accepts the socket connection, and does handshake with extag_doclienthandshake. The parties can use control commands to for example close connection. If the data length is set zero, the packet includes a (network byte order) 2-octet control command a argument. These include opening a connection (0) and closing a connection (1). These command are handled by extag_handlecontrol.
4 The ssextagent library
	The ssextagent library implements the interface described in External Agent Interface Specification in a staighteforward manner.
5 The functions of module External agent interface
	File extagent-internal.h C-functions: void extag_acceptcbk(IN EventLoopIONotification notification, IN void *context) Description: ExtagConnectionStatus extag_acceptconnection(IN int fd, INOUT ExtagConnection **conn) Description: ExtagStatus extag_closeconnection(IN ExtagConnection *connection) Description: void extag_delete_packets(PacketListNode *n) Description: void extag_destroypacket(Packet *p) Description: void extag_eloopcallback(IN EventLoopIONotification notification, IN void *context) Description: ExtagStatus extag_finishhandshake(IN ExtagConnection *conn) Description: ExtagStatus extag_getport(unsigned short tcpport) Description: ExtagConnectionStatus extag_initconnection(IN int fd, OUT ExtagConnection **conn) Description: void extag_packettoasc(char *str, Packet *packet, Bool includedata, int maxlen) Description: ExtagStatus extag_recvpacket(ExtagConnection *connection) Description: ExtagStatus extag_sendpacket(ExtagConnection *connection) Description: void extag_seteventloopreqs(ExtagConnection *connection) Description: File extagent-packet.h C-functions: void net_addresstoasc(char *str, int base, DomainAddress *addr) Description: Formats the DomainAddress in the caller allocated char array pointed by str. If base is 10, notation "ip.ip.ip.ip tcp-port x.x x.x.x.x" is used, otherwise a hexadesimal notation is used. Bool net_cmpraddr(IN DomainAddress *a, IN DomainAddress *b) Description: Compares two DomainAddresses. True is returned on match, False otherwise. NetSndStatus net_deliverpacket(IN Packet *pckt, IN DomainAddress *addr) Description: Adds the packet to the appropriate connections packetstosend list. If no connection to the desired peer exists, establishes one. Return NET_SND_COMPLETE on success, NET_SND_INVALIDADDRESS if the address was invalid. void net_destroypacket(Packet *packet) Description: Delete packet and its contents. NetRcvStatus net_getrecpaddr(IN Packet *pckt, OUT DomainAddress *addr) Description: Extracts the recipients address from the packet, and returns NET_RCV_COMPLETE. void net_packettoasc(char *str, Packet *packet, Bool includedata, int maxlen) Description: Formats a packet in the caller allocated char array pointed by str. If include data is set, the packet data is dumped along with packet header. never uses more than maxlen chars. NetRcvStatus net_recvpacket(struct Connection *connection) Description: Receives as any packets from connection as possible. When (non-blocking) reading socket fails, gives control back to caller and sets the progrptr of the last packet to the number of bytes read of that packet. Returns either NET_RCV_COMPLETE if all was sent and NET_RCV_PARTIALLYSENT otherwise. If socket fails, NET_RCV_SOCKETSENDFAILED is returned. NetSndStatus net_sendpacket(struct Connection *) Description: Send as many packet from the connections packetstosend list as the socket accepts. When writing becomes impossible, gives control back to the caller, and sets the progrptr of the last packet to the number of bytes sent of that packet. Returns either NET_SND_COMPLETE if all was sent and NET_SND_PARTIALLYSENT otherwise. If socket fails, NET_SND_SOCKETSENDFAILED is returned. File extagent.h C-functions: ExtagStatus extag_begindelivery(IN struct ExtagConnection *connection) Description: Let the packet delivery begin. Before calling this this, the extagent system won't call the callback in the kernel. This allows the interface agent to start up. Returns EXTAG_OK. ExtagStatus extag_initialize(unsigned short tcpport, IN ExtagAcceptCallback cbk) Description: Initializes the extagent system. Call this before any other extagenting functions. After this, one would typically call extag_registerpacketcallback(). After calling this function the extagent system begins to listen a tcp-port ExtagStatus extag_send(IN struct ExtagConnection* conn, IN int size, IN uchar* data) Description: Sends the -long message (in bytes) to the external agent. Does not free any memory the arguments hold. Essentially gathers a extagent packet from the arguments and passes it to extag_deliverpacket(). The memory area that contains the packet data may be modified after this function returns; a copy of the packet is made internally if needed. Return EXTAG_OK if succeeded, EXTAG_FAILED if the packet cannot be delivered (SIZE <= 0 or tcp connection fails). ExtagStatus extag_shutdown(INOUT void) Description: Extagent shutdown. Closes all the connections (and notifies the peer also), and unregisters the fd's to event loop. Event loop is not aborted. Return EXTAG_OK. File ssextagent.h C-functions: ExtagStatus ssexact_blockingread(IN SsexConn* conn, OUT char** data, OUT int* len) Description: void ssexact_close(IN SsexConn* conn) Description: Closes the connection to the SchemeStation domain indentified by fd. int ssexact_fd(IN SsexConn* conn) Description: Returns the number of the fd for selecting etc. ExtagStatus ssexact_initialize(IN char *hostname, IN unsigned long ipaddr, IN unsigned short tcpport, OUT SsexConn** conn) Description: Initializes the ssextag interface instance and opens a connection to the SchemeStation domain specified by addr. Returns a fd for which the following semantics apply: * To ensure consistent operations, the fd should be read or written only using ssextag_send and ssextag_read functions. * The ssextag_read function call is non-blocking provided that it has been preceded by a call to select() returns ExtagStatus ssexact_read(IN SsexConn* conn, OUT char** data, OUT int* len) Description: Tries to read a message from the connection given by fd. The fd should be got from ssextag_initialize. The function unblocking sematics provided that the call is preceded by a successfull call to select that has returned ready to ready status for the fd. Unless this condition is met, blocking may take place. The data read is stored to dynamically allocated memory pointed the pointer data. The caller is responsible for deallocating the memory. The function returns EXTAG_OK and the length len on successful completition - that is when a complete message has been stored in the data struct. If the read discontinues in the middle of the packet, EXTAG_UNFINISHED is returned, the data is set to point to the read data, the len is set to the read message length. The ssextag_read maintains its internal state and automagically continues to read the unfinished message on next call. ExtagStatus ssexact_send(IN SsexConn* conn, IN int size, IN char* data) Description: Sends the size-long message (in bytes) data to the ActorAddress. Does not free any memory the arguments hold. The memory area that contains the packet data may be modified after this function returns; a copy of the packet is made internally if needed. Return EXTAG_OK if succeeded, EXTAG_FAILED if the packet cannot be delivered (SIZE <= 0 or tcp connection fails). A call to ssextact_send _may_ block. int ssextact_fd(IN SsexConn* conn) Description: Returns the fd from the SsexConn struct. File extagent-internal.h C-functions: void extag_acceptcbk(IN EventLoopIONotification notification, IN void *context) Description: ExtagConnectionStatus extag_acceptconnection(IN int fd, INOUT ExtagConnection **conn) Description: ExtagStatus extag_closeconnection(IN ExtagConnection *connection) Description: void extag_delete_packets(PacketListNode *n) Description: void extag_destroypacket(Packet *p) Description: void extag_eloopcallback(IN EventLoopIONotification notification, IN void *context) Description: ExtagStatus extag_finishhandshake(IN ExtagConnection *conn) Description: ExtagStatus extag_getport(unsigned short tcpport) Description: ExtagConnectionStatus extag_initconnection(IN int fd, OUT ExtagConnection **conn) Description: void extag_packettoasc(char *str, Packet *packet, Bool includedata, int maxlen) Description: ExtagStatus extag_recvpacket(ExtagConnection *connection) Description: ExtagStatus extag_sendpacket(ExtagConnection *connection) Description: void extag_seteventloopreqs(ExtagConnection *connection) Description: File ssextagent.h C-functions: ExtagStatus ssexact_blockingread(IN SsexConn* conn, OUT char** data, OUT int* len) Description: void ssexact_close(IN SsexConn* conn) Description: Closes the connection to the SchemeStation domain indentified by fd. int ssexact_fd(IN SsexConn* conn) Description: Returns the number of the fd for selecting etc. ExtagStatus ssexact_initialize(IN char *hostname, IN unsigned long ipaddr, IN unsigned short tcpport, OUT SsexConn** conn) Description: Initializes the ssextag interface instance and opens a connection to the SchemeStation domain specified by addr. Returns a fd for which the following semantics apply: * To ensure consistent operations, the fd should be read or written only using ssextag_send and ssextag_read functions. * The ssextag_read function call is non-blocking provided that it has been preceded by a call to select() returns ExtagStatus ssexact_read(IN SsexConn* conn, OUT char** data, OUT int* len) Description: Tries to read a message from the connection given by fd. The fd should be got from ssextag_initialize. The function unblocking sematics provided that the call is preceded by a successfull call to select that has returned ready to ready status for the fd. Unless this condition is met, blocking may take place. The data read is stored to dynamically allocated memory pointed the pointer data. The caller is responsible for deallocating the memory. The function returns EXTAG_OK and the length len on successful completition - that is when a complete message has been stored in the data struct. If the read discontinues in the middle of the packet, EXTAG_UNFINISHED is returned, the data is set to point to the read data, the len is set to the read message length. The ssextag_read maintains its internal state and automagically continues to read the unfinished message on next call. ExtagStatus ssexact_send(IN SsexConn* conn, IN int size, IN char* data) Description: Sends the size-long message (in bytes) data to the ActorAddress. Does not free any memory the arguments hold. The memory area that contains the packet data may be modified after this function returns; a copy of the packet is made internally if needed. Return EXTAG_OK if succeeded, EXTAG_FAILED if the packet cannot be delivered (SIZE <= 0 or tcp connection fails). A call to ssextact_send _may_ block. int ssextact_fd(IN SsexConn* conn) Description: Returns the fd from the SsexConn struct.