Menu [hide]

CCID API

print
In DCCP-TP, there are two CCIDs associated with each connection, one corresponding to the local CCID feature value that handles packets transmitted by the connection (referred to as the CCID sender in the code) and the other corresponding to the remote CCID feature value that handles packets received by the connection (referred to as the CCID receiver in the code). Note that the CCID sender has some need to process received packets (received acknowledgments) and the receiver has need to send some packets (acknowledgements). The two CCIDs need not be the same, and the DCCP-TP code is structured to handle the necessary cross-exchange.

To create a new CCID, first add a sender open function to the ccidSenderOpenFuncs array in dctpRcv.c, and a receiver open function to the ccidRcvrOpenFuncs array, at the index corresponding to the CCID number. CCID open functions take a dctpSocket pointer as an argument and return 0 for a successful open or less than 0 for an error.

CCID open functions are called when the connection first reaches PARTOPEN (for a client socket) or OPEN (for a server socket), and whenever the CCID changes after that. The sender open function is responsible for setting the ccidSenderFuncs pointer in the dctpSocket structure to a pointer to a dctpCcidSenderFuncs structure that contains pointers to the action routines for the CCID sender. It also will usually allocate additional memory for whatever state is necessary and set the ccidSenderInfo field in the socket. Receiver open functionis perform similar duties for the ccidRcvrFuncs and ccidRcvrInfo fields of the socket. If either of the open functions fails (returns less than 0), the connection is closed.

The dctpCcidSenderFuncs structure contains pointers to the following routines:

  • int rcvAckabllePacket(dctpSocket *sock, dctpPacket *pkt) — Called for each packet received by the connection that has made it to the acknowledgeable packet stage. The CCID sender can use this to process packets that have been acknowledged by this packet. The return value is ignored.

  • uint32_t getCurrentRTO(dctpSocket *sock) — Returns the current round-trip-timeout estimate in microseconds.

  • int processCcidOption(dctpSocket *sock, dctppacket *pkt, uint_t op, uint_t oplen, uint8_t **ops) — Called when an option in the CCID-specific range has been received. 'op' is the option value, 'oplen' is the length of the option data (not including the option value and length fields), and 'ops' points to the option data. Returns non-zero if there is a fatal option error.

  • void rcvdSlowRcvr(dctpSocket *sock) — Called when a Slow Receiver option is received.

  • void rcvdDataDropped(dctpSocket *sock, uint64_t ackno, uint8_t *ops, uint_t oplen) — Called when a Data Dropped option is received. 'ackno' is the acknowledgment number in the packet that contained the option, 'ops' points to the options data and 'oplen' is the length of the data.

  • uint64_t rcvdAckVector(dctpSocket *sock, uint64_t ackno, uint8_t *ops, uint_t oplen, uint_t vytpe) — Called when an Ack Vector option is received. 'ackno' is the first packet acknowledged by the Ack Vector. 'ops' points to the vector data of 'oplen' length. 'vtype' is 0 for Ack Vector 0 or 1 for Ack Vector 1. Returns the ack number where the next Ack Vector option will begin processing.

  • void rcvdNdpCount(dctpSocket *sock, dctpPacket *pkt, uint64_t ndpcout) — Called when an NDP Count option is received. 'ndpcount' is the count field from the option.

  • void rcvdTimestampEcho(dctpSocket *sock, uint32_t tsecho, uint32_t etime) — Called when a Timestamp Echo option is received. 'tsecho' is the echoed timestamp value. 'etime' is the received elapsed time.

  • void rcvdElapsedTime(dctpSocket *sock, uint64_t ackno, uint32_t etime) — Called when an Elapsed Time option is received. 'ackno' is the ack number in the containing packet. 'etime' is the received elapsed time value.

  • void addOptions(dctpSocket *sock, dctpPacket *pkt, uint8_t *ops, uint_t *oplen) — Called when a packet is about to be transmitted. This is the sender CCID's opportunity to add any options to the packet. 'ops' points to the beginning of the array of options for the packet. 'oplen' points to the current end of the options. If options are added, 'oplen' must be updated.

  • int dataXmtOK(dctpSocket *sock, uint_t len) — Called when a packet is available to be transmitted (of length 'len'). Return 0 to allow the packet to be transmitted, less than 0 to queue the packet for later attempt.

  • int xmtPkt(dctpSocket *sock, dctpPacket *pkt) — Called just before a packet is to be transmitted, after all options have been added and all DCCP header fields have been set. The CCID sender can use this opportunity to record whatever information about the packet is necessary. Returns 0 for no errors or -1 if fatal errors are encountered. A failure return will close the connection.

  • void destroyCcidInfo(dctpSocket *sock) — Called when the CCID is no longer the valid CCID for this connection. Normally this occurs when the connection leaves the OPEN state but can also happen when a new CCID is negotiated. The function frees any memory used by the CCID and sets the ccidSenderFuncs and ccidSenderInfo fields of the socket to NULL.

The CCID sender code is also responsible for calling dctpiXmtPacket each time a change in CCID state would allow transmission of a new data packet and for calling the ackAcked function of the receiver CCID (see below) when a transmitted acknowledgment packet is acknowledged.

The dctpCcidRcvrFuncs structure contains pointers to the following routines:

  • int rcvAckblePacket(dctpSocket *sock, dctpPacket *pkt) — Called when an acknowledgeable packet has been received. The return value is ignored.

  • int processCcidOption(dctpSocket *sock, uint_t op, uint_t oplen, uint8_t **ops) — Called when an option in the CCID-specific range has been received. 'op' is the option value, 'oplen' is the length of the option data (not including the option value and length fields), and 'ops' points to the option data). Returns non-zero if there is a fatal option error.

  • void ackAcked(dctpSocket *sock, uint64_t seqno, uint8_t ackState) — Called by the sender CCID when a transmitted acknowledgment packet has been acknowledged. 'seqno' is the sequence number of the acknowledged packet. 'ackState' is the Ack Vector state of the acknowledgment (Received or Marked).

  • void addOptions(dctpSocket *sock, dctpPacket *pkt, uint8_t *ops, uint_t *oplen) — Called when a packet is about to be transmitted. This is the receiver CCID's opportunity to add any options to the packet. 'ops' points to the beginning of the array of options for the packet. 'oplen' points to the current end of the options. If options are added, 'oplen' must be updated.

  • void destroyCcidInfo(dctpSocket *sock) — Called when the CCID is no longer the valid CCID for this connection. Normally this occurs when the connection leaves the OPEN state but can also happen when a new CCID is negotiated. The function frees any memory used by the CCID and sets the ccidRcvrFuncs and ccidRcvrInfo fields of the socket to NULL.

Created by: trphelan last modification: Thursday 29 of May, 2008 [20:44:13 UTC] by trphelan