appCORE - coreNetChanAccept()

NAME

coreNetChanAccept() -- accept an incoming TCP connection.

SYNOPSIS

include "appcore.h"

int coreNetChanAccept( coreNetChanAcceptSPEC_t* s, coreHandle_t* h )

DESCRIPTION

The coreNetChanAccept() function is used to accept an incoming TCP connection. The coreNetChanAcceptSPEC_t data type configures how the incoming channel will be processed. The socket descriptor is initialized from the accept event. Channel options are setup via the Options element. The channel is established after coreNetChanAccept() returns with a successful handle and return code. The returned handle is used for all subsequent operations.

Channel Events
The EventHandler is required and will be called in the source thread for all future channel events.

Channel events are enumerated by the coreNetChanEvent_t data type. Once a channel is connected, only a data receive events or a disconnect event can be received. Flow control events are optional and are discussed below.

Transmit Processing
There are three (3) methods available to transmit data on a channel. Each is most apporpriate for one of the above mentioned modes.

For stream mode, we normally want to send a buffer of data. The function coreNetChanPayloadMsg() is used to create a netCORE payload message. The payload in this message is transmitted on the channel by coreMsgDispatch() function.

In message mode ...

In core message mode, we are able to send a coreMsg_t directly over a channel by simply dispatching it over a channel in this mode. The far end of the channel sees this message as a coreMsg_t.

In each case, the channel's handle instructs appCORE to route the message to the netCORE actor. In this way, the channel handle is operating much like a UNIX style file descriptor.

Options
The Options element of the accept data type allows the caller to control channel operation. Channel modes are stream, message, or core message. Stream mode is the default.

Stream Mode
In stream mode, the channel is processed as a stream of bytes. Default parameters specify a standard IP MTU read size. Read size can be specified via the Options element. The number of outstanding read operations can be specified via the Options and is honored if the platform supports it. Stream mode is the default mode of operation.

Message Mode
Message mode assumes the network data stream is organized into messages, each with a fixed length header and an optional, variable length payload. The user provides the size of the header and a function to validate the header and query the payload length. netCORE will use this information and the function to process the data stream. In this mode, each receive event contains a distinct message. This mode is selected via option coreNetChanOptionMSG

During processing, the user function is called by netCORE to query the header and return the size of the payload. This function must not block, or perform extended processing. This function may perform header validation and indicate the result of the validation via its return code. A negative return code is interpreted as an error and the channel will be closed.

Read size and number of read operations is not relevant in message mode.

Core Message Mode
In core message mode the network data stream is organized into appCORE messages. appCORE messages contain a fixed size header, and an optional, variable length payload. In this mode, only the MSGCORE option needs to be specified.

This mode of operation allows the exchange of appCORE messages across network channels by simply sending an appCORE message on a netCORE channel. The message dispatch function routes the message to the netCORE actor automatically.

Read size and number of read operations is not relevant in core message mode. This mode is selected via option coreNetChanOptionMSGCORE

Flow Control
Transmit and receive flow control are available options. If either are enabled via the Options element, then coreNetChanEventRECEIVE_FLOW and coreNetChanTRANSMIT_FLOW events can be received.

Transmit Flow Control
In progress...

Receive Flow Control
In progress...

PARAMETERS

s

   typedef struct  _core_net_chan_accept_spec_
   {
      SOCKET SockFd;

         The socket descriptor returned in accept event

      void* UserCntxt; 

         The user's context, returned in the coreNetChanEventMsg_t

      coreNetAddrSPEC_t Address;

         ? - we use this to set the address family - move to OptionSPEC?

      coreNetOptionSPEC_t Options;

         Channel Options - set these with coreNetChanSet function
      
      int (*EventHandler)( coreNetChanEventMsg_t* );

         The user's thread local event handler. This function is called
         in the context of the user's thread for channel events.
   }
   coreNetChanAcceptSPEC_t;

h
    pointer to a coreHandle_t. If successful, this is the new channel's handle.

Sample Code


coreNetChanAcceptSPEC_t Spec;
coreNetChanMsgSPEC_t MsgSpec;

   // pMsg points to the netCORE ACCEPT event message
		
   bzero( &Spec, sizeof(Spec) );
   Spec.UserCntxt = pMsg->UserCntxt;
   Spec.EventHandler = YourChannelEventHandler;
   Spec.SockFd = pMsg->SockFd;  

   // Setup channel mode
   
   switch( YourChanMode )
   {
   case coreNetChanOptionMSG:       

      bzero( &MsgSpec, sizeof(MsgSpec) );
      MsgSpec.HeaderLength = sizeof(YourMsgHeader);
      MsgSpec.GetPayloadSize = YourMsgGetPayloadSize;

      // Set the option on the Accept data type

      coreNetChanOptionSet( &Spec.Options,
                             coreNetChanOptionMSG,
                             &MsgSpec,
                             sizeof(MsgSpec) );
      break;

   case coreNetChanOptionMSGCORE:

      coreNetChanOptionSet( &Spec.Options,
                             coreNetChanOptionMSGCORE,
                             NULL,
                             0 );
      break;
   }

   coreNetChanAccept( &Spec, &h );

RETURN VALUE

errno Value	Condition
ENOTSUP	Not supported - netCORE is not running.
EINVAL	Argument NULL or handler function not defined.

MULTI-THREAD SAFETY LEVEL

MT-safe.