tfRegisterSocketCB

Table of Contents >> SSL Programmer's Reference

#include <trsocket.h>

int tfRegisterSocketCB	(
	int socketDescriptor,
	ttUserSocketCBFuncPtr socketCBFuncPtr,
	int eventFlags
	);

Function Description

This function is used to register a function call upon completion of one of more socket events. This allows the user to issue non-blocking calls, and get a call back upon completion of one or more socket events as described in the table below. The call back function will be called repeatedly each time one or more of the events registered for occur until the user cancel the event(s) with another call to tfRegisterSocketCB() with a new event flag value. For example, if the user registers for a receive event (TM_CB_RECV), then the call back function will be called, in the context of the receive task, every time a packet is received from the network and queued in the socket receive queue.

Note that most of the call back calls will be made in the context of the receive task. TM_CB_SOCKET_ERROR, TM_CB_RESET, TM_CB_CLOSE_COMPLETE events call backs could be made in the context of an application task or the receive task. In all the other events, call backs will be made in the context of the receive task. Therefore processing should be kept at a minimum in the call back function. In a multi-tasking environment, the user call back function should set a flag or increase a counter and signal the user application task.

The call back function must adhere to the ttUserSocketCBFunc prototype.

Parameters

• socketDescriptor

  The socket descriptor to register the call back for.

• sockettCBFuncPtr

  A pointer to the user-defined ttUserSocketCBFunc function to call when one or more of the registered events occur.

• eventFlags

  One or more of the flags described below and OR'ed together.

EventFlags

• TM_CB_CONNECT_COMPLT

  Register for a connection complete call back (TCP socket only).

• TM_CB_ACCEPT

  Register for a call back when a remote host has established a connection to our listening server (TCP socket only).

• TM_CB_RECV

  Register for a call back when incoming data has arrived from our peer.

• TM_CB_RECV_OOB

  Register for a call back when out-of-band data has arrived from our peer (TCP socket only).

• TM_CB_SEND_COMPLT

  Register for a call back when the data that we are sending has been acked by the peer host (TCP socket only).

• TM_CB_REMOTE_CLOSE

  Register for a call back when our peer has shutdown the connection (TCP socket only).

• TM_CB_SOCKET_ERROR

  Register for a call back when an error occured on the connection.

• TM_CB_RESET

  Register for a call back when the peer has sent a reset on the connection (TCP socket only).

• TM_CB_CLOSE_COMPLT

  Register for a call back when the user issued close has completed (TCP socket only).

• TM_CB_WRITE_READY

  Indicates that there is more room on the send queue. The user can now send more data on the connection given by the socketDescriptor.

• TM_CB_TCPVECT_CLOSE

  Register for a call back when the TCP vector has closed, i.e. when the TCP connection has transitioned to the CLOSED state (non listening TCP socket only). Since the listening socket will be released as soon as tfClose() has been called, there is no need for such an event on a listening TCP socket.

• TM_CB_SSL_ESTABLISHED

  Register for a callback when an SSL connection is established on the socketDescriptor

• TM_CB_SSL_SEND_CLOSE

  Register for a callback when an SSL connection is closed for the sending path (still able to receive if TM_CB_SSL_RECV_CLOSE is not set)

• TM_CB_SSL_RECV_CLOSE

  Register for a callback when an SSL connection is closed for the receiving path (still able to send if TM_CB_SSL_SEND_CLOSE is not set)

• TM_CB_SSL_HANDSHK_FAILURE

  Register for a callback when an SSL handshake failure happens

• TM_CB_SSL_BADCERTIFICATE

  Register for a callback when bad_certificate alert message is sent or received

• TM_CB_SSL_HANDSHK_PROCESS

  Register for a callback when Treck receives SSL data that needs processing. Use this to improve receive task responsiveness by offloading CPU-intensive cryptographic operations.

Actions to be Taken by the User

• TM_CB_CONNECT_COMPLT

  Non-blocking connect issued earlier by the user has now completed, and the connection is established with the peer on the socketDescriptor. The user is now able to send and recv data on the connection given by the socketDescriptor.

• TM_CB_ACCEPT

  A remote host has established a connection to the listening server socketDescriptor. The user can now issue an accept call to retrieve the socket descriptor of the newly established connection.

• TM_CB_RECV

  Incoming data has arrived on the connection given by socketDescriptor. The user can now issue any of the allowed recv calls for the protocol associated with the socket to retrieve the incoming data.

• TM_CB_RECV_OOB

  Incoming out-of-band data has arrived on the connection given by socketDescriptor. The user can use the appropriate method to retrieve the out of band data as described in the recv section above.

• TM_CB_SEND_COMPLT

  Some sent data has been received, and acked by the peer. The user can issue tfGetSendCompltBytes() to retrieve the actual amount of bytes that have been received and acked since the last call to tfGetSendCompltBytes().

• TM_CB_REMOTE_CLOSE

  Our peer has shutdown the connection (sent a FIN). No more new data will be coming. The user should empty the socket's receive queue using any of the recv calls. The user must then close the connection (using tfClose()).

• TM_CB_WRITE_READY

  Indicates that there is more room on the send queue. The user can now send more data on the connection given by the socketDescriptor.

• TM_CB_SOCKET_ERROR

  An error has occured on the connection. The user can issue a send or recv call to retrieve the error as described in the send and recv sections. Note that recv() will return all outstanding incoming data before returning the error. The user should then issue tfClose() to close the connection.

• TM_CB_RESET

  The peer has sent a RESET. The user needs to issue tfClose() to close the socket.

• TM_CB_CLOSE_COMPLT

  The user issued tfClose() has now completed.

• TM_CB_TCPVECT_CLOSE

  The TCP vector has closed, i.e. the TCP connection has transitioned to the CLOSED state. After both the TM_CB_TCPVECT_CLOSE, and TM_CB_CLOSE_COMPLT events have occurred, all resources associated with the TCP socket have been freed.

• TM_CB_SSL_ESTABLISHED

  Proceed with your send() and recv() calls. Don't use shutdown() because it operates on the underlying socket. Use tfClose() to disconnect (or one of the SSL functions to teardown the SSL layer, only).

• TM_CB_SSL_HANDSHK_FAILURE

  You would typically call tfClose() to disconnect after receiving this. Any data you send() will not be encrypted.

• TM_CB_SSL_HANDSHK_PROCESS

  Call tfSslUserProcessHandshake() to process the pending SSL operations. You might do this, for example, in the same thread that calls recv(). You may receive TM_CB_SSL_ESTABLISHED or TM_CB_SSL_HANDSHK_FAILURE during processing.

Returns

• TM_ENOERROR

  Success

• TM_SOCKET_ERROR

  Failure

Note:

TM_SOCKET_ERROR means that this socket call has failed and the errorCode has been set on the socket itself. To retrieve the socket error the user must call tfGetSocketError(socketDescriptor).

Possible socket errors

• TM_EBADF

  socketDescriptor is not a valid descriptor.

• TM_EINVAL

  socketCBFuncPtr is NULL and eventFlags is non-zero.

Table of Contents >> SSL Programmer's Reference