Io Function Reference

Io
This is the low level IO system and supports moving opaque information between processes and or network hosts based on a configuration file. It also supports configurable encryption on all links. The IO system uses an integer handle to reference an existing virtual circuit and character pointers to reference messages. There is a single input queue for all inbound messages with action type EVTDRVR, the normal application message type. Each virtual circuit has it's own output queue and input queue for messages in transit.
LAW OF CONSERVATION OF MESSAGE SPACE: A message may be created either my directly calling ioMkMsg() or ioMkRsp() or by receiving a message (ioRcv()). When a message is sent (transmitted) it's space if freed. A received message must be freed or re-sent.

If you send a message you have received, without modifying it's virtual circuit, the message returns to it's origin.
The I/O system is an event driven system, that is, when a message arrives it's action type is used as the event type and all events registered to that action code are fired. The default action for application messages is EVTDRVR.
Different events can be used for communication between any two parts of a system. This communication is invisible to the application, but no messages can be received or sent if the process doesn't call ioWait().
A description of the protocol API is forthcomming and will describe how to add a new protocol to the Io system.


devDo	devReq	ioAddCfg	ioAddProtocol	ioClose
ioCloseAll	ioClrWatOut	ioctFnd	ioctInit	ioctReg
ioDregWat	ioDoEvent	ioDupMsg	ioFree	ioFwdDst
ioFwdId	ioGetCfg	ioGetMsgId	ioGetMsgLen	ioGetPath
ioGetHndl	ioGetPeer	ioGetThd	ioInit	ioMakMsg
ioMakRsp	ioNew	ioOutBusy	ioOpen	ioPing
ioPingAsync	ioRcv	ioRegEvent	ioRegWat	ioSetWatOut
ioSetThd	ioSetEvt	ioSnd	ioWait	ioWaitUs
ioWakNow	mInit	mLck	mUnLck


int	devDo( int devId )

Perform all delayed events with the specified "devId" If the "devId" is zero, perform all delayed events. There are currently 30 Delayed Event Ids defined as "Dev1" through "Dev30". Delayed events are volatile, that is, they only occurr once after each registration. A delayed event call-back can request another delayed event of the same ID but it won't happen until the next devDo().
Delayed Events are really handy to use inside a signal handler so the time in the handler is minimized. In this case, you should call devDo in the main line or when you get around to it.

Request a delayed event. There are currently 30 Delayed Event Ids defined as "Dev1" through "Dev30". The "devId" determines who or when it will be executed. The "func" to be called at "do" time, and "conTxt" to be passed to the called function. The call back func's prototype.

int callBack( void *conTxt );


int	devReq( int devId, pfi_t func, void* conTxt )

Delayed events are volatile, that is, they only occurr once after each registration. A delayed event call-back can request another delayed event of the same ID but it won't happen until the next devDo().
Delayed Events are really handy to use inside a signal handler so the time in the handler is minimized. In this case, you should call devDo in the main line or when you get around to it.

Add a port configuration the the local process's IO system. A typical call: ioAddCfg( TCP, "MyCmdQue", "Barf", "4201", "Blowfish", "how now brindle bovine" ); Would add a port (or destination) named "MyCmdQue" on the external IP of host "Barf", at port 4201, encrypted using the Blowfish algorythm, and an encryption key of "how now brindle bovine". If "enc" and "key" are not needed, they should be NULL. If "loc" is "*" or "localhost" the local host loop back is used.

Add a protocol to the local hosts IO capabilities. This is used by ioInit to install the TCP protocol, and has been used in the past to install HTTP (a character based socket protocol), TTY (single character keyboard ptotocol), and other protocols. The argument "protocol" must not be the same as TCP, "name" is it's label (like "TCP") and "init" points to an initialization function which will be passed a newly created protocol control block which it must fill in with such things as input, output, and exception handler function pointers.

Close a socket "sd" and free it's connection control.

Close all sockets. Used by sys.c after forking a new sub-process and before exec. This prevents the new process from being encumbered (inheriting) a raft of opens sockets which may be connected to no telling where.

This clears the wait on output flag for sd in the master wait list.

Find the argument registered to the supplied socket descriptor. Returns the registered pointer else NULL if not found.

Initialize the connection tracking layer. The IO Connection Tracking layer is used to track low level IO connections.

Register an argument to the supplied socket desriptor. When a registered socket disconnects, the registered call-back funtion is called to allow the application to clean up it's own information about the socket.

Deregister a socket (or file) descriptor, remove all call-back references from ioWait's waitlist.


int	ioAddCfg( int proto, char* name, char* loc, char* phy, char* enc, char* key )


int	ioAddProtocol( int protocol, char* name, pfi_t init )


int	ioClose( int sd )


int	ioCloseAll( )


int	ioClrWatOut( int sd )


void*	ioctFnd( int sd )


int	ioctInit( int argc, char** argv )


int	ioctReg( int sd, void* arg, pfi_t cbFunc )


int	ioDregWat( int sd )


int	ioDoEvent( int type, void* option )

Execute an event of type "type". All handlers (call-backs) registered to this event will be called and passed both the "context" which was established at registeration time and the ioDoEvents "option" arguments.
CALL-BACK FUNCTION: int ioEvent( void *registeredContext, void *option)

Duplicate the message pointed to by "mp" (the header is copied). The allocated length of the new message is of length "len".

Free a message created by the IO system either by ioMakMsg() or ioRcv().

Forward an existing message pointed to by "msg", to destination named "dest". The message is of length "len". The message may have originally been created with a much greater length than was actually needed, so "len" indicates the number of bytes to actually transmit. Returns OK if all went well, else ERR. As in all IO send operations, the message space is free after transmission.

Simular to ioFwdDst() above but it sends the message across an already existing virtual circuit indicated by "handle". The handle may be acquired by using ioGetHndl( msg* ) or by ioGetPath( dest* ).

Get IO configured ports. If "out" points to a NULL string, ioGetCfg goes to the beginning of it's config chain, else it goes to the next entry. The output looks like: PROTO LogicalName Location PhysicalName [EncryptionMeth Key] This is the same information as required by ioAddCfg() above.

Returns the Socket IF of the messages.

Returns the byte count of the message pointed to by "msg". There is no convenient way to error check this macro's return, so be warned.

Returns an IO message handle which may be used to create a message or send an existing message. This call looks in it's port chain then it's config chain for a defined queue, then conects to the queue and sends/receives an IO "ping" message. If all went well an IO handle is returned else ERR.

Get the handle associated with the message pointed to by "msg".

Return the logical name of the peer process.

Return the thread ID of the IO message.

Initialize the IO system (called from infInit()). Returns argc.

Create an IO messages of length "len" and associated with IO handle (virtual circuit) "handle".

Create a response message to the existing message pointed to by "msg", and of length "len".

Create a new message destined for "name" queue and of length "len". Returns a pointer to a new IO message.

Returns TRUE if the output queue is not empty, else FALSE if it is. This is used by some processes before exiting to see if their last message has been transmitted.

Open a server queue and begin listening for connection requests.

Pings are intended to connect or test a virtual circuit and incidentally excahange information about processes. Send an IO ping message across the circuit refereneced by "handle" then wait for a response. The ascii string int the buffer pointed to by "msg" will be appended to the ping and buffer will be used to receive the response message. The receiving process may access the entire ping message by registering a function associated with the event EVTPING. The caller will get the entire ping response message in it's buffer pointed to by "msg". The ping message format is: "hostName,procName,PingSeq#,PeerPid,callerMsg" NOTE: Two events are used "under the covers" to implement ping, EVTPING1 (the request) and EVTPING2 (the reponse).

Pings are intended to connect or test a virtual circuit and incidentally excahange information about processes. The asynchronous ping may also be used as a keep alive or stall alarm. Send an IO ping message across the circuit refereneced by "handle". The ascii string pointed to by "msg" will be appended to the ping message and then be transmitted to the connection peer process. If the transmitt was successful, the call returns OK immediately after transmitting the "Ping" request. If a transmitt error occurred, ERR is returned. The receiving process may access the entire ping message by registering a function associated with the event EVTPING. The originating process may see any return message (and determine if the ping was successful) by registering a call-back to event PINGECHO. The ping message format is: "hostName,procName,PingSeq#,PeerPid,callerMsg" NOTE: Two events are used "under the covers" to implement ping, EVTPING1 (the request) and EVTPING2 (the reponse).

Receive an IO message. Returns a message pointer if one is available and NULL if not.


int	ioDupMsg( char* mp, ulong len )


int	ioFree( char* msg )


int	ioFwdDst( char* msg, char* dest, int len )


int	ioFwdId( char* msg, int handle )


int	ioGetCfg( char* out, char* name )


int	ioGetMsgId( char* msg )


ulong	ioGetMsgLen( char* msg )


int	ioGetPath( char* queName )


int	ioGetHndl( char* msg )


char*	ioGetPeer( char* mp )


int	ioGetThd( char* mp )


int	ioInit( int argc, char** argv )


char*	ioMakMsg( int handle, ulong len )


char*	ioMakRsp( char* msg, int length )


char*	ioNew( char* name, int len )


int	ioOutBusy( int handle )


int	ioOpen( char* name )


int	ioPing( int hndl, char* msg )


int	ioPingAsync( int hndl, char* msg )


char*	ioRcv( )


int	ioRegEvent( int eventType, pfi_t cbFunc, void* context )

Register an event of type "eventType". When this event occurs the function "cbFunc" will be called and passed this "context" and the ioDoEvent "option" as arguments.
CALL-BACK FUNCTION: int ioEvent( void *registeredContext, void *option)


int	ioRegWat( int sd, pfi_t inputCbFunc, pfi_t outputCbFunc, pfi_t exceptionCbFunc, void* contxt )

Register an I/O socket (or file) descriptor's callbacks. The "inputCbFunc" is for input interrupts, the "outputCbFunc" is for output interrupts, and the "exceptionCbFunc" is for exceptions. The "contxt" variable is provided to all three call-backs.
CALL-BACK FUNCTION: int call-back( void *contxt)

This sets the wait on output flag for sd in the master wait list.

Sets the threadID in the IO message header.

Sets the event number in the IO message header. Please see ioRegEvent() for receifing process details. Was ioSetMsgTyp, a macro for this is now available in io1.h.

Sends the low level IO message pointed to by "mp" and of length "len". This is actually a macro for _ioSnd which requires a pointer pointer to mp (the macro fixes this). Returns 0 (zero) else ERR.

Wait for "timeout" milliseconds or until an event transpires which returns OK. Returns OK if an event retuned one else NULL for timeout. This macro calls ioWaitUs()

This is the low level ioWait waits for microseconds.

Wake ioWait before it's timeout. Caveat: ioWait will return an OK as if a message was received. ioWakNow returns OK This is handy for delayed events or signals etc. that need to wake the main line. A worker thread can signal the main thread which is in ioWait().