Socket: 2 Simple Example

The sample application Appl/SDK_C/Talk provides an example of a simple application using the Socket library.

To understand how the program works, you should, of course, look at its source code. The following is a high-level overview of what the Talk example illustrates: a simple client-server connection in which the server awaits connections, the client connects, and then the two exchange data. Note: this application assumes that the host device (the client) has already connected to the server. Remote connections are usually made through PPP or Point-to-Point Protocol. See SocketOpenDomainMedium() discussed in Hardware Ports.

The example performs the following steps:

Allocate memory in which to store data.
When sending or receiving data, you need to provide a pointer to a buffer containing the data to be sent or received. Thus, the buffer should be in a block which can either be locked down as needed or is in fixed memory. Programs often spawn a separate thread to receive data from the socket; if this thread needs to lock down a memory block in which to store the data, then make sure that the thread can lock down the memory block. See the Multithreading chapter to learn about managing threads.
(If you follow the multi-threaded approach, be aware that when the Socket's owning thread exits, it frees the Socket. To allow a Socket to survive the exit of its thread, use SocketSetIntSocketOption() to change its owning thread.)
For this simple example, we're using a small buffer to handle the receipt of data, so we declare it as a global variable so it resides in the application's fixed memory:

char recvBuf[16];

Client Side: Make Sure Connected to Domain
Depending on the nature of the device and application, you may need to make sure that the device is connected to the communication domain. In the Talk sample application, we make sure that the device is dialed in to an ISP: an AccessPointControl object prompts the user to choose an ISP, and a call to SocketOpenDomainMedium() opens a PPP connection to that ISP.
Client Side: Get Address For Other Side of Connection.
The Talk application allows the user to connect with another machine by specifying that machine's address. The Talk application creates a controller gadget by which the user can specify an address. SocketGetAddressController() returns the controller class' pointer; ObjInstantiate() creates an object of the class.
The following code is called when the application opens. It creates the controller gadget, initializes its data, and places it in a dialog box.

ctrlClass = 
  SocketGetAddressController(theAddress.SA_domain));

ctrlOb = 
  ObjInstantiate( 
    HandleOf(GeodeGetOptrNS(@AddressDialog)),
    ctrlClass);

@call ctrlOb::MSG_SOCKET_ADDRESS_CONTROL_SET_ACTION(
  ConstructOptr(0,TO_PROCESS), MSG_CTP_VALID);

@call
  GeodeGetOptrNS(@AddressDialog)::MSG_GEN_ADD_CHILD(
    ctrlOb, CCO_FIRST);

@call ctrlOb::MSG_GEN_SET_USABLE(VUM_NOW);

When the user enters an address, the following code is called. It gets the selected address from the address controller and packages it up into a form the Socket library can use.

MSG_SOCKET_ADDRESS_CONTROL_GET_ADDRESSES returns a chunk with raw address data based on the address entered by the user. SocketResolve() reduces this raw address data to a primitive form that can be used for making connections.

adArray = @call ctrlOb::MSG_SOCKET_ADDRESS_CONTROL_GET_ADDRESSES();

address1 = ChunkArrayElementToPtrHandles(
  HandleOf(ctrlOb), adArray, 0,0);

theAddress.SA_addressSize = 
  SocketResolve(
    theAddress.SA_domain, (byte *)&address1[1],
    address1->SACA_opaqueSize, addressBuffer,
    MAX_ADDRESS_SIZE);

LMemFreeHandles(HandleOf(ctrlOb), adArray);

Client Side: Create and Connect Socket.
The Client side now creates a socket for its side of the connection and attempts to connect to the address extracted from the address controller. The socket will be of the stream delivery type.

dataSocket = SocketCreate(SDT_STREAM);

SocketConnect(
  dataSocket, (SocketAddress *) &theAddress,
  SOCKET_NO_TIMEOUT);

Server Side: Create Socket and Accept Connection(s)
On the server side, the application spawns a separate thread to handle incoming connections.

There are two "sockets" created on this, the server side of the connection. The first socket is bound to a particular port, and "listens" for incoming connections. It is possible to accept more than one connection over the listening socket--each accepted connection is represented by another socket to represent this side of the new particular connection.

listenSocket = SocketCreate(SDT_STREAM);

SocketBind(listenSocket, theAddress.SA_port, 0);

SocketListen(listenSocket, 5);

dataSocket = SocketAccept(
  listenSocket, SOCKET_NO_TIMEOUT);

Either Side: Send Data
In this example, the data to send is taken from a text object. The program loads the text into a block of memory, locks the block down to get a pointer to it, then transmits the data.

textBlock = @call
  GeodeGetOptrNS(@InText)::
  MSG_VIS_TEXT_GET_ALL_BLOCK(NullHandle);

textPtr = MemLock(textBlock);

textSize = LocalStringSize(textPtr);

SocketSend(
  dataSocket, textPtr, textSize, 0, 
  (SocketAddress *)0);

MemFree(textBlock);

Either Side: Wait For and Receive Data
The application's listening thread waits for data to arrive and stores it away in a buffer when it does arrive. It processes the incoming data and gets ready for the next piece of data.

while ((
  datasize = SocketRecv(
    dataSocket, recvBuf, sizeof recvBuf, 
    SOCKET_NO_TIMEOUT, 0, (SocketAddress *)0))
  != 0)

{ @call 
  GeodeGetOptrNS(@OutText)::MSG_VIS_TEXT_APPEND_PTR(
    recvBuf, datasize); }

Either Side: Close Connection
The application has a Close button. When the user presses this button, the application shuts down its side of the connection. The SocketCloseSend() routine partially shuts down the socket so that it can receive data, but cannot send it; also, the routine sends a signal to the other side that the connection is closing.

if (listenSocket) { 
  SocketClose(listenSocket);
  listenSocket = 0; }

SocketCloseSend(dataSocket);

Either Side: Detect Closed Connection and Close Socket
When receiving data, if either side seems to have received a zero-length packet, it checks to see if an exception has occurred, specifically to see if the connection has closed. (When SocketRecv() detects an error, it sets the thread error value, which may be retrieved via ThreadGetError() .) If the connection has closed, then Talk closes the sockets on this side of the connection.

if (ThreadGetError() == SE_CONNECTION_CLOSED) { 
  if (listenSocket) {
    SocketClose(listenSocket);
    listenSocket = 0; }
  SocketClose(dataSocket); }

Both Sides: Sockets Freed When Thread Exits
Lest you are worried about these Sockets you have created but not freed, know that they will be freed automatically when the owning thread exits. (To allow a Socket to survive its thread's exit, you must assign the Socket to a new thread.)

GEOS SDK TechDocs|

1 Introduction | Next:

3 Addresses