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.9.7 The functions of module External agent interface |
| File extagent-internal.h
C-functions:
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:
File ssextagent.h
C-functions:
- ExtagStatus ssexact_blockingread(IN SsexConn* conn,
OUT char** data,
OUT int* len)
-
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:
File ssextagent.h
C-functions:
- ExtagStatus ssexact_blockingread(IN SsexConn* conn,
OUT char** data,
OUT int* len)
-
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. |
|