tfRegisterSocketCB

Jump to: navigation, search

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


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.


Returns

  • TM_ENOERROR
    Success
  • TM_SOCKET_ERROR
    Failure


Note 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