CORDET Framework - C2 Implementation
|
Interface for a client socket to be used by InStreams and OutStreams. More...
Go to the source code of this file.
Functions | |
void | CrFwClientSocketInitAction (FwPrDesc_t prDesc) |
Initialization action for the client socket. More... | |
void | CrFwClientSocketShutdownAction (FwSmDesc_t smDesc) |
Shutdown action for the client socket. More... | |
void | CrFwClientSocketInitCheck (FwPrDesc_t prDesc) |
Initialization check for the client socket. More... | |
void | CrFwClientSocketConfigAction (FwPrDesc_t prDesc) |
Configuration action for the client socket. More... | |
void | CrFwClientSocketPoll () |
Poll the client socket to check whether a new packet has arrived. More... | |
CrFwPckt_t | CrFwClientSocketPcktCollect (CrFwDestSrc_t pcktSrc) |
Function implementing the Packet Collect Operation for the client socket. More... | |
CrFwBool_t | CrFwClientSocketIsPcktAvail (CrFwDestSrc_t pcktSrc) |
Function implementing the Packet Available Check Operation for the client socket. More... | |
CrFwBool_t | CrFwClientSocketPcktHandover (CrFwPckt_t pckt) |
Function implementing the hand-over operation for the client socket. More... | |
void | CrFwClientSocketSetPort (unsigned short n) |
Set the port number for the socket. More... | |
void | CrFwClientSocketSetHost (char *name) |
Set the host name of the server. More... | |
Interface for a client socket to be used by InStreams and OutStreams.
This module defines the functions through which the InStreams and OutStreams control the socket in order to receive packets (InStream) or to send them (OutStream). These functions are used to customize the InStreams (see CrFwInStreamUserPar.h
) and the OutStreams (see CrFwInStreamUserPar.h
) which interact with the socket. More precisely:
CrFwClientSocketInitAction
should be used as the initialization action for the InStreams and OutStreams.CrFwClientSocketInitCheck
should be used as the initialization check action for the InStreams and OutStreams.CrFwClientSocketConfigAction
should be used as the configuration action for the InStreams and OutStreams.CrFwClientSocketShutdownAction
should be used as the shutdown action for the InStreams and OutStreams.CrFwClientSocketPcktCollect
should be used as the Packet Collect operation for the InStreams.CrFwClientSocketIsPcktAvail
should be used as the Packet Available Check operation for the InStreams.CrFwClientSocketPcktHandover
should be used as the Packet Hand-Over operation for the OutStreams.The functions in this module should be accessed in mutual exclusion. Compliance with this constraint is not enforced and is therefore under the responsibility of the caller.
The socket controlled by this module is built as a client socket using the Internet domain and the TCP protocol. It is designed to work with the server socket of CrFwServerSocket.h
.
The socket must be initialized with the port number and with the host name for its socket (these are defined through functions CrFwClientSocketSetPort
and CrFwClientSocketSetHost
).
The socket assumes a polling approach for incoming packets: function CrFwClientSocketPoll
should be called periodically by an external scheduler. This function performs a non-blocking read on the socket to check whether a packet is available at the socket. If a packet is available, the function retrieves its source and forwards it to the associated InStream by calling function CrFwInStreamPcktAvail
on the InStream to signal the arrival of a new packet. This causes all pending packets from that source to be collected by the InStream and stored in its Packet Queue.
The implementation of this module assumes that, at each read operation, an entire packet is received. The situation where the packet is split into fragments during the transmission process is not handled. In practice, this socket is intended for the case where the socket is local to the host platform (i.e. where the host name is "localhost" and both sender and receiver of a packet are located on the same platform).
Packets which are read from the socket are stored in a buffer (the Read Buffer). This is an array of bytes whose size is equal to the maximum size of a middleware packet. The Read Buffer can be either "full" (if its first byte is different from zero) or "empty" (if its first byte has been cleared).
The packet hand-over operation for OutStreams is implemented in function CrFwClientSocketPcktHandover
which performs a non-blocking write to the socket.
If an error is encountered while performing a system call, this module uses function perror
to print an error message and, if the error was encountered in the initialization or configuration action, it sets the outcome of the action to 0 ("failure") and returns.
This module assumes that the maximum length of a packet is smaller than 256 bytes. Compliance with this constraint is verified in the Initialization Check.
Mode of Use of a Client Socket Module
This module may be controlled jointly by multiple InStreams and/or OutStreams. Its socket is initialized when the first of the these components is initialized (the initialization of the other InStreams/OutStreams has no effect). The socket is reset whenever one of the InStreams/OutStreams is reset. The socket is shut down whenever one of the InStreams/OutStreams is shut down (the shutdown of the other InStreams/OutStreams has no effect).
This client socket should only be initialized after its server socket has completed its initialization.
After the client socket has completed its configuration, users should periodically call function CrFwClientSocketPoll
to poll the socket for any incoming packets.
If the server socket is closed, a call to the socket read operation in the client socket (i.e. a call to CrFwClientSocketPoll
) will result in the last packet sent by the server socket being read from the socket. Hence, correct operation requires that the client socket be shutdown before server socket.
This file is part of the CORDET Framework.
This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
For information on alternative licensing, please contact P&P Software GmbH.
Definition in file CrFwClientSocket.h.
void CrFwClientSocketConfigAction | ( | FwPrDesc_t | prDesc | ) |
Configuration action for the client socket.
This action clears the Read Buffer and executes the Configuration Action of the base InStream (function CrFwInStreamDefConfigAction
)
prDesc | the configuration procedure descriptor. |
Definition at line 181 of file CrFwClientSocket.c.
void CrFwClientSocketInitAction | ( | FwPrDesc_t | prDesc | ) |
Initialization action for the client socket.
If the client socket has already been initialized, this function calls the Initialization Action of the base InStream/OutStream and then returns. If the client socket has not yet been initialized, this action:
prDesc | the initialization procedure descriptor. |
Definition at line 71 of file CrFwClientSocket.c.
void CrFwClientSocketInitCheck | ( | FwPrDesc_t | prDesc | ) |
Initialization check for the client socket.
The check is successful if: the maximum length of a packet (as retrieved from CrFwPcktGetMaxLength
) is smaller than 256; and the port number and server host name have been set.
prDesc | the initialization procedure descriptor. |
Definition at line 158 of file CrFwClientSocket.c.
CrFwBool_t CrFwClientSocketIsPcktAvail | ( | CrFwDestSrc_t | pcktSrc | ) |
Function implementing the Packet Available Check Operation for the client socket.
This function implements the following logic:
packetSource
, the function returns 1.packetSource
, the function performs a non-blocking read on the socket.packetSource
, the function returns 0.packetSource
, the function stores it in the Read Buffer and then returns 1.pcktSrc | the source associated to the InStream |
Definition at line 250 of file CrFwClientSocket.c.
CrFwPckt_t CrFwClientSocketPcktCollect | ( | CrFwDestSrc_t | pcktSrc | ) |
Function implementing the Packet Collect Operation for the client socket.
If the packet in the Read Buffer has a source attribute equal to pcktSrc
, this function:
CrFwPcktMake
If the Read Buffer holds a packet from a source other then pcktSrc
, this function returns NULL. Note that the logic of the client socket module guarantees that the Read Buffer will always be full when this function is called.
pcktSrc | the source associated to the InStream |
Definition at line 232 of file CrFwClientSocket.c.
CrFwBool_t CrFwClientSocketPcktHandover | ( | CrFwPckt_t | pckt | ) |
Function implementing the hand-over operation for the client socket.
This function performs a non-blocking write on the socket and, if it succeeds, it returns 1; otherwise, it returns 0.
pckt | the packet to be written to the socket |
Definition at line 284 of file CrFwClientSocket.c.
void CrFwClientSocketPoll | ( | ) |
Poll the client socket to check whether a new packet has arrived.
This function should be called periodically by an external scheduler. If there is a pending packet (i.e. of the Read Buffer is full), its source is determined, and then function CrFwInStreamPcktAvail
is called on the InStream associated to that packet source. If there is no pending packet (i.e. if the Read Buffer is empty), a non-blocking read is performed on the socket to check whether a packet is available at the socket. If a packet is available, it is placed into the Read Buffer, its source is determined, and then function CrFwInStreamPcktAvail
is called on the InStream associated to that packet source. In a realistic implementation, the source of the incoming packet would be determined from the packet itself (which holds its source in its header). This implementation is intended for use with the test cases of CrFwSocketTestCase.h
and then the incoming packets are routed to the 6-th InStream.
Definition at line 198 of file CrFwClientSocket.c.
void CrFwClientSocketSetHost | ( | char * | name | ) |
Set the host name of the server.
If a local socket is being created, the host name should be set to "localhost".
name | the host number. |
Definition at line 307 of file CrFwClientSocket.c.
void CrFwClientSocketSetPort | ( | unsigned short | n | ) |
Set the port number for the socket.
The port number must be an integer greater than 2000.
n | the port number. |
Definition at line 302 of file CrFwClientSocket.c.
void CrFwClientSocketShutdownAction | ( | FwSmDesc_t | smDesc | ) |
Shutdown action for the client socket.
If the client socket has already been shut down, this function calls the Shutdown Action of the base InStream/OutStream and then returns. If the client socket has not yet been shut down, this action executes the Shutdown Action of the base InStream/OutStream, releases the Read Buffer, and closes the socket.
smDesc | the InStream or OutStream State Machine descriptor. |
Definition at line 138 of file CrFwClientSocket.c.