You are here

TutorialLibraryTest ApplicationDownload
Tutorial[Library]Test ApplicationDownload

Socket Library Manual

The socket library of this tutorial can be downloaded via the Download section of this page. The archive should simply be extracted into the folder of your choice. The directory /sources contains the source code of the library. The archive also contains two folders enabling to compile under Windows (Visual Studio) or Linux (makefile).

Compilation under Linux

To compile the library under linux, open a console in the directory containing the file libSock.mk and execute the following commands:

  • make -f libSock.mk all
  • make -f libSock.mk install

The library will then be compiled (libSock.so) and installed in the directory /user/lib. Folder /Includes is also created. It contains the header files with the different library function prototypes.

Compilation under Windows

The Visual Studio projection in the /Windows directory enables to compile easily the library. Important output files of this compilation are libSock.dll and libSock.lib.

If you need to create a project from another compilator, do not forget to define the symbol LIBSOCK_EXPORTS in the preprocessor commands definition. This command enables the following compiler directive __declspec (dllexport), which allows some functions to be exported from the library (see file libSock.h.

Testing the library

A test application for this library is available under the Download section of this page and is discussed further in section Test Application.

Manual

Each function provided by the library is described below:




Function SK_NewServer

This function creates a new server. A server can handle multiple connections from multiples clients.

SockError_C SK_NewServer (
   unsigned int maxLink,
   unsigned int *pID
);
  • maxLink : [in] Maximum number of clients/connections this server can handle.
  • pID : [out] New server ID. This value must be used to reference the new server.
  • Return value : Error structure containing error codes in case of failure.




Function SK_NewClient

This function creates a new client. A client can handle only one connection to a single server.

SockError_C SK_NewClient (
   unsigned int *pID
);
  • pID : [out] New client ID. This value must be used to reference the new client.
  • Return value : Error structure containing error codes in case of failure.




Function SK_DeleteCS

This function deletes a client or server, and frees all associated resources.

SockError_C SK_DeleteCS (
   unsigned int ID
);
  • ID : [in] Client or server ID to delete.
  • Return value : Error structure containing error codes in case of failure.




Function SK_Listen

This function activates or deactivates the listening process on a server.

SockError_C SK_Listen (
   unsigned int ID,
   bool state,
   unsigned int maxWaiting,
   unsigned int port
);
  • ID : [in] Server ID on which listening process must be activated/deactivated.
  • state : [in] True to activate the listening process.
  • maxWaiting : [in] Maximum number of clients that can be simultaneously waiting for connection acceptance (if state is TRUE).
  • port : [in] Port number for listening (if state is TRUE).
  • Return value : Error structure containing error codes in case of failure.




Function SK_Accept

This function validates the next connection request from the pending queue. This function must be used with a server and listening process must be first enabled.

SockError_C SK_Accept (
   unsigned int ID,
   int waitTime,
   unsigned int *pIDLink
);
  • ID : [in] Server ID on which a connection request must be accepted.
  • waitTime : [in] Maximum blocking time if no any request is avialable. -1 means function can block for an infinite time. 0 means function make a simple test and returns immediately whatever the result.
  • pIDLink : [out] Link ID for the new link, in case of success. 0 in case of failure.
  • Return value : Error structure containing error codes in case of failure.




Function SK_Connect

This function tries to connect to a server at a given address.

SockError_C SK_Connect (
   unsigned int ID,
   int waitTime,
   char* addr,
   unsigned int port,
   unsigned int *pIDLink
);
  • ID : [in] ID of the client to connect to a server.
  • waitTime : [in] Maximum blocking time if connection can not be established immediately. -1 means function can block for an infinite time. 0 means function make a simple test and returns immediately whatever the result.
  • addr : [in] Server address. This can be a server name, or a server address in decimal form (e.g : "127.0.0.1").
  • port : [in] Server port number.
  • pIDLink : [out] Link ID for the new link, in case of success. 0 in case of failure..
  • Return value : Error structure containing error codes in case of failure.




Function SK_Disconnect

This function close a connection link.

SockError_C SK_Disconnect (
   unsigned int ID,
   unsigned int IDLink
);
  • ID : [in] Client or Server ID managing the connection link.
  • IDLink : [in] Link ID identifying the connection to close.
  • Return value : Error structure containing error codes in case of failure.




Function SK_Write

This functions writes data on a given connection link.

SockError_C SK_Write (
   unsigned int ID,
   unsigned int IDLink,
   unsigned char *pData,
   int *pLength,
   int waitTime_ms
);
  • ID : [in] Client or Server ID managing the connection link on which data must be sent.
  • IDLink : [in] Link ID identifying the connection on which data must be sent.
  • pData : [in] Pointer to data to send.
  • pLength : [in, out] Number of data to send, in Bytes. After function call, this value is updated in order to reflect the actual number of data sent.
  • waitTime_ms : [in] Maximum blocking time if data can not be written because internal transmission buffer is full. -1 means function can block for an infinite time. 0 means function make a simple test and returns immediately whatever the result.
  • Return value : Error structure containing error codes in case of failure.




Function SK_Read

This functions enables to wait for data from simultaneous connection links at the same time. Function waits until at least one Byte of data is available on one of the given links. Then, data are received from this single link so that data from different links are not mixed together.

SockError_C SK_Read (
   S_ReadList *pList,
   unsigned int listLength,
   unsigned char *pBuffer,
   int *pLength,
   int waitTime_ms,
   S_ReadList *pIDRead,
   bool dontBlockIfData
);
  • pList : [in] Pointer to a list of S_ReadList structure specifying connection links on which reading must take place.
  • listLength : [in] Number of items in pList.
  • pBuffer : [in] Pointer to a buffer for data reception.
  • pLength : [in, out] Number of data to read, in Bytes. After function call, this value is updated with the actual number of data read. If a connection link is disconnected, this value is updated to -1.
  • waitTime_ms : [in] Maximum blocking time if no enough data is available in the internal reception buffer. -1 means function can block for an infinite time. 0 means function make a simple test and returns immediately whatever the result.
  • pIDRead : [out] Address of a S_ReadList variable updated with the link ID of the connection on which data have been received.
  • dontBlockIfData : [in] If TRUE, function returns as soon as at least one Byte has been received on one of the given connection links, even if number of requested data is not reached and deadline has not expired.
  • Return value : Error structure containing error codes in case of failure.