-
Notifications
You must be signed in to change notification settings - Fork 6
Mockets.h
- Mockets(3)
- setIdentifier(1)
- getIdentifier (0)
- registerPeerUnreachableWarningCallback (2)
- registerSuspendReceivedWarningCallback (2)
- registerPeerReachableCallback (2)
- getStatistics (0)
- bind (2)
- connect(2)
- connect(3)
- connect (4)
- reEstablishConn (1)
- resumeAndRestoreState (2)
- connectAsync (2)
- finishConnect (0)
- getRemoteAddress (0)
- getRemotePort (0)
- getLocalAddress (0)
- getLocalPort (0)
- isConnected (0)
- close (0)
- suspend (2)
- getState (1)
- enableCrossSequencing (1)
- isCrossSequencingEnabled (0)
- getSender (2)
- getOutgoingBufferSize (0)
- send (8)
- gsend (8+)
- gsend (10)
- getNextMessageSize (1)
- getCumulativeSizeOfAvailableMessages (0)
- receive (3)
- receive (2)
- sreceive (3+)
- replace (9)
- cancel (3)
- setConnectionLingerTime (1)
- getConnectionLingerTime (0)
- getMTU (0)
- getMaximumMTU (0)
- activateBandwidthEstimation (1)
- activateCongestionControl (0)
- debugStateCapture (0)
- useTwoWayHandshake (0)
- setTransmitRateLimit (1)
- setKeepAliveTimeout (1)
- disableKeepAlive (0)
- setInitialAssumedRTT (1)
- setMaximumRTO (1)
- setMinimumRTO (1)
- setRTOFactor (1)
- setRTOConstant (1
- disableRetransmitCountFactorInRTO (0)
- setMaximumWindowSize (1)
- setSAckTransmitTimeout (1)
- setConnectTimeout (1)
- setUDPReceiveConnectionTimeout (1)
- setUDPReceiveTimeout (1)
Return type: Void
Parameters:
-
const char *pszConfigFile = NULL Path to the configuration file.
-
CommInterface *pCI = NULL
-
bool bDeleteCIWhenDone = false
Description: The main class for a client application to use the Mockets communication library. Similar in functionality to a socket it is used by a client to establish a connection to a server and then communicate with the server.
Return type: Void
Parameters:
- const char *pszConfigFile = NULL User friendly identifier for this Mocket instance.
Description: Sets a string to use as the application or user friendly identifier for this Mocket instance. The identifier is used when sending out statistics and when logging information (some suggestions include the name of the application, the purpose for this Mocket, ...). The pszIdentifier may be set to NULL to clear a previously set identifier.
Note: The string is copied internally, so the caller does not need to preserve it.
Return type: const char* Mocket’s instance identifier.
Parameters:
- none
Description: Returns the user friendly identifier for this Mocket instance, will return NULL if there is no identifier set.
Return type: int Time in ms since last contact.
Parameters:
- PeerUnreachableWarningCallbackFnPtr pCallbackFn Callback function to be invoked.
- void *pCallbackArg Pointer to callback argument.
Description: Register a callback function to be invoked when no data (or Keepalive) has been received from the peer’s Mocket. The callback will indicate the time (in milliseconds) since last contact, if the callback returns true, the Mocket connection will be closed. An optional argument (which will be passed in during the callback) may be passed when setting the callback.
Return type: int Time in ms since the connection has been suspended.
Parameters:
- PeerUnreachableWarningCallbackFnPtr pCallbackFn Callback function to be invoked.
- void *pCallbackArg Pointer to callback argument.
Description: Register a callback function to be invoked when a suspend message has been received. The callback will indicate the time (in milliseconds) since the connection has been suspended. An optional argument may be passed when setting the callback which will be passed in during the callback.
Return type: Int Time in ms since last contact.
Parameters:
- PeerReachableCallbackFnPtr pCallbackFn Callback function to be invoked.
- void *pCallbackArg Pointer to callback argument.
Description: Register a callback function to be invoked once peerUnreachable has been invoked (and subsequently we have heard from the peer). The callback will indicate the time (in milliseconds) since last contact. An optional argument may be passed when setting the callback which will be passed in during the callback.
Return type: MocketStats * Pointer to Statistics class.
Parameters:
- None
Description: Returns a pointer to the Statistics class that maintains statistics about this Mocket connection.
Note: This must not be deallocated by the caller.
Return type: int 0 Success; <0 Error code.
Parameters:
- const char *pszBindAddr Address string
- uint16 ui16BindPort Port
Description: Binds the local end point to a particular address (interface) and port. Calls to this method will work if invoked before calling 'connect()', otherwise, it will return an error code.
Note: Must be invoked before connect.
Return type: int 0 Success; <0 Error code.
Parameters:
- const char *pszRemoteHost String containing the remote host address.
- uint16 ui16RemotePort Remote host port.
Description: Attempt to connect to a Mocket Server at the specified remote host on the specified remote port. The host may be a hostname that can be resolved to an IP address or an IP address in string format (e.g. "127.0.0.1"). The default connect timeout is 30 seconds. Returns 0 if successful or a negative value in case of failure.
Return type: int 0 Success; <0 Error code.
Parameters:
- const char *pszRemoteHost String containing the remote host address.
- uint16 ui16RemotePort Remote host port.
- int64 i64Timeout Timeout.
Description: Same as the connect method above with the additional capability of specifying an explicit timeout value. The timeout value must be in milliseconds.
Return type: int 0 Success; <0 Error code.
Parameters:
- const char *pszRemoteHost String containing the remote host address.
- uint16 ui16RemotePort Remote host port.
- bool bPreExchangeKeys Secury key exchange flag.
- int64 i64Timeout = 0 Timeout.
Description: Same as the connect method above with the additional capability of specifying an explicit timeout value and to specify if security keys should be exchange at connection time. The timeout value must be in milliseconds. If security keys are exchanged reEstablishConn (supports change in the network attachment point) is supported both for client and server side while simpleSuspend only for client side. A default value can be used for the timeout parameter.
Return type: int 0 Success; <0 Error code.
Parameters:
- uint32 ui32ReEstablishTimeout = DEFAULT_RESUME_TIMEOUT
Description: Connect to the remote host after a change of the machine's IP address and/or port due to a change in the network attachment. Returns 0 if successful or a negative value in case of failure.
Return type: int 0 Success; <0 Error code.
Parameters: NOMADSUtil::Reader *pr uint32 ui32ReEstablishTimeout = DEFAULT_RESUME_TIMEOUT
Description: Initialize a new Mocket after a suspension, then create an objectDefroster to extract values from the previous node. Finally it Connect to the remote host and exchange the messages ack and resume.
Return type: int 0 Success; <0 Error code.
Parameters:
- const char *pszRemoteHost String containing the remote host address.
- uint16 ui16RemotePort Remote host port.
Description: Attempt to connect to a Mocket Server at the specified remote host on the specified remote port. The host may be a hostname that can be resolved to an IP address or an IP address in string format (e.g. "127.0.0.1"). The connection attempt is asynchronous, this call will return 0 on success and a callback will notify the application when the connection attempt succeeded or failed. Returns a negative value in case of failure.
Return type: Int 1 Connection is established; 0 Connection process is in progress; <0 Error code.
Parameters:
- None
Description: Check whether a connection has been established for this Mocket. To use with connectAsync. Returns 1 if the connection is established, 0 if the connection process is in progress, <0 (the error code returned by connect()) if the connection process failed (no connection was established).
Return type: uint32 Remote Host Address
Parameters:
- None
Description: Return the remote host address to which the connection has been established.
Return type: uint16 Remote Host Port
Parameters:
- None
Description: Return the remote port to which the connection has been established.
Return type: uint32 Local host connection bounded address.
Parameters:
- None
Description: Return the remote host address to which the connection has been established.
Return type: uint16 Local host connection bounded port.
Parameters:
- None
Description: Return the port on the local host to which this connection is bounded to.
Return type: bool True Mocket is connected; False Mocket is not connected.
Parameters:
- None
Description: Returns true if the Mocket is currently connected.
Return type: int 0 Success; <0 Error code
Parameters:
- None
Description: Closes the current open connection to a remote endpoint. Returns 0 if the connection is being closed, <0 in case of error.
Return type: int 0 Success; <0 Error code
Parameters:
- uint32 ui32FlushDataTimeout = DEFAULT_FLUSH_DATA_TIMEOUT
- uint32 ui32SuspendTimeout = DEFAULT_SUSPEND_TIMEOUT
Description: Invoked by the application to suspend the Mocket. Returns 0 in case of the connection being suspended, <0 in case of error.
Return type: int 0 Success; <0 Error code
Parameters:
- NOMADSUtil::Writer *pw
Description: Invoked by the application if suspend ends with success. Create an ObjectFreezer that contains the state of the Mocket connection.
Return type: int 0 Success; <0 Error code
Parameters:
- bool bEnable True for enabling Cross Sequencing.
Description: Enables or disables Cross Sequencing across the reliable sequenced and unreliable sequenced packets.
Return type: bool True CrossSequencing is enabled; False CrossSequencing not enabled.
Parameters:
- none
Description: Returns the current setting for cross sequencing.
Return type: MessageSender Instance of the MessageSender class.
Parameters:
- bool bReliable True for reliable.
- bool bSequenced True for sequenced.
Description: Obtains a new sender for the specified combination of reliability and sequencing parameters.
Return type: uint32 Space available in bytes.
Parameters:
- none
Description: Returns the amount of space available in the outgoing (transmit) buffer, which implies that any call to send() or gsend() with a message size that is less than this value will not block.
Note: Large messages may be fragmented, resulting in the message using up more space, therefore, do not assume this is an exact value.
Return type: int 0 Success; <0 Error code.
Parameters:
- bool bReliable True for reliable.
- bool bSequenced True for sequenced.
- const void *pBuf Message buffer pointer.
- uint32 ui32BufSize Buffer size.
- uint16 ui16Tag Tag value.
- uint8 ui8Priority Message priority.
- uint32 ui32EnqueueTimeout Enqueueing timeout.
- uint32 ui32RetryTimeout Retransmission timeout.
Description: Enqueues the specified data for transmission using the specified reliability and sequencing requirements. The tag identifies the type of the packet and the priority indicates the priority for the packet. The enqueue timeout indicates the length of time in milliseconds for which the method will wait. If there is no room in the outgoing buffer (a zero value indicates wait forever). The retry timeout indicates the length of time for which the transmitter will retransmit the packet to ensure successful delivery (a zero value indicates retry with no time limit). Returns 0 if successful, <0 in case of error.
Return type: int 0 Success; <0 Error code.
Parameters:
- bool bReliable True for reliable.
- bool bSequenced True for sequenced.
- uint16 ui16Tag Tag value.
- uint8 ui8Priority Message priority.
- uint32 ui32EnqueueTimeout Enqueueing timeout.
- uint32 ui32RetryTimeout Retransmission timeout.
- const void *pBuf1 Message Buffer pointer.
- uint32 ui32BufSize1 Message Buffer size.
- …
Description: Variable argument version of send (to handle a gather write). Caller can pass in any number of buffer and buffer size pairs.
Note: The last argument, after all buffer and buffer size pairs, must be NULL.
Return type: int 0 Success; <0 Error code.
Parameters:
- bool bReliable True for reliable.
- bool bSequenced True for sequenced.
- uint16 ui16Tag Tag value.
- uint8 ui8Priority Message priority.
- uint32 ui32EnqueueTimeout Enqueueing timeout.
- uint32 ui32RetryTimeout Retransmission timeout.
- const void *pBuf1 Message Buffer pointer.
- uint32 ui32BufSize1 Message Buffer size.
- va_list valist1
- va_list valist2
Description: Variable argument version of send (to handle a gather write).
Note: The last argument, after all buffer and buffer size pairs, must be NULL.
Return type: int 0 Success; <0 Error code.
Parameters:
- int64 i64Timeout = 0 No data timeout.
Description: If no message is available, the call will block based on the timeout parameter. Not specifying a timeout or a timeout of 0 implies that the default timeout should be used whereas a timeout of -1 implies wait indefinitely.
Return type: uint32 >0 Cumulative size of all messages that are ready to be delivered, 0 No messages available.
Parameters:
- none
Description: Returns the cumulative size of all messages that are ready to be delivered to the application or 0 in the case of no messages being available.
Note: This method does not provide an indication that the connection has been closed.
Return type: int 0 No data, -1 Connection being closed, >0 Number of bytes that were copied into the buffer.
Parameters:
- void *pBuf Message buffer.
- uint32 ui32BufSize Message buffer size.
- int64 i64Timeout = 0 No data timeout.
Description: Retrieves the data from next message that is ready to be delivered to the application. At most ui32BufSize bytes are copied into the specified buffer. Not specifying a timeout or a timeout of 0 implies that the default timeout should be used whereas a timeout of -1 implies wait indefinitely. Returns the number of bytes that were copied into the buffer, -1 in case of the connection being closed, 0 in case no data is available within the specified timeout.
Note: Any additional data in the packet that will not fit in the buffer is discarded.
Return type: int 0 No data, -1 Connection being closed, >0 Number of bytes that were copied into the buffer.
Parameters:
- void **ppBuf Pointer to ppbuf.
- int64 i64Timeout = 0 No data timeout.
Description: Retrieves the data from next message that is ready to be delivered to the application. A new buffer of the size necessary for the message is allocated and the pointer to the buffer is copied into ppBuf. Not specifying a timeout or a timeout of 0 implies that the default timeout should be used whereas a timeout of -1 implies wait indefinitely. Returns the number of bytes that were copied into the buffer, -1 in case of the connection being closed, 0 in case no data is available within the specified timeout.
Note:
- This method is inefficient because it results in a new memory allocation for every receive. Consider using getNextMessageSize and maintaining a single buffer in the application.
- The application is responsible for deallocating the memory by calling free().
Return type: int 0 No data, -1 Connection being closed, >0 Number of bytes that were copied into the buffer.
Parameters:
- int64 i64Timeout No data dimeout.
- void *pBuf1 Message buffer.
- uint32 ui32BufSize1 Message buffer size.
- …
Description: Retrieves the data from the next message that is ready to be delivered to the application. Not specifying a timeout or a timeout of 0 implies that the default timeout should be used whereas a timeout of -1 implies wait indefinitely. The data is scattered into the buffers that are passed into the method. The pointer to the buffer and the buffer size arguments must be passed in pairs. The last argument should be NULL. Returns the number of bytes that were copied into the buffers, -1 in case of the connection being closed, 0 in case no data is available within the specified timeout.
Note:
- If the caller passes in three buffers, (e.g., sreceive (-1, pBufOne, 8, pBufTwo, 1024, pBufThree, 4096)), and the method returns 4000, the implication is that 8 bytes were read into pBufOne, 1024 bytes into pBufTwo, and the remaining 2968 bytes into pBufThree.
- Any additional data in the packet that will not fit in the buffers is discarded.
Return type: int 0 Success, <0 Error code
Parameters:
- bool bReliable True for reliable.
- bool bSequenced True for sequenced.
- const void *pBuf Pointer to data buffer.
- uint32 ui32BufSize Data buffer size.
- uint16 ui16OldTag Tag to look for.
- uint16 ui16NewTag New tag.
- uint8 ui8Priority New priority.
- uint32 ui32EnqueueTimeout New enqueuer timeout.
- uint32 ui32RetryTimeout New retry timeout.
Description: First cancels any previously enqueued messages that have been tagged with the specified OldTag value and then transmits the new message using the specified parameters. See documentation for cancel() and send() for more details.
Note: There may be no old messages to cancel - in which case this call behaves just like a send().
Return type: int 0 Success, <0 Error code
Parameters:
- bool bReliable True for reliable.
- bool bSequenced True for sequenced.
- uint16 ui16TagId Tag to look for.
Description: Cancels (deletes) previously enqueued messages that have been tagged with the specified tag
Note: Note that the messages may be pending transmission (which applies to all flows) or may have already been transmitted but not yet acknowledged (which only applies to reliable flows).
Return type: int 0 Success, <0 Error code
Parameters:
- uint32 ui32LingerTime Unsent data timeout.
Description: Sets the length of time (in milliseconds) for which a connection should linger before closing in case there is unsent data. A timeout value of 0 implies that the connection should wait indefinitely until all data has been sent.
Return type: uint32 Linger time.
Parameters:
- none
Description: Returns the current setting for the connection linger time.
Return type: uint16 MTU.
Parameters:
- none
Description: Returns the current MTU that is in effect
Return type: uint16 Maximum MTU.
Parameters:
- none
Description: Returns the maximum MTU that may be used
Return type: int 0 Success, <0 Error code
Parameters:
- uint16 ui16InitialAssumedBandwidth = DEFAULT_INITIAL_ASSUMED_BANDWIDTH Assumed Bandwidth.
Description: Activates bandwidth estimation.
Note: Must be called after connect().
Return type: int 0 Success, <0 Error code
Parameters:
- none.
Description: Activates congestion control.
Note: Must be called after connect().
Return type: none
Parameters:
- none
Description: Used to activate debugging of the state capture during Mockets migration. This will disable sending of messages with odd sequence number in order to perform a migration with messages in the queues.
Return type: none
Parameters:
- none
Description: Activates two-way handshake instead of default four-way handshake.
Return type: int 0 Success, <0 Error code.
Parameters:
- uint32 ui32TransmitRateLimit Outgoing Bandwidth limit.
Description: Set a bandwidth limit on the outgoing flow of data. ui32TransmitRateLimit is specified in bytes per second. A value of 0 indicates no limit
Return type: int 0 Success, <0 Error code.
Parameters:
- uint32 ui32TransmitRateLimit Outgoing Bandwidth limit.
Description: Set a bandwidth limit on the outgoing flow of data. ui32TransmitRateLimit is specified in bytes per second. A value of 0 indicates no limit
Return type: none
Parameters:
- uint16 ui16Timeout Keep alive timeout.
Description: Set the keep Alive Timeout.
Note: Even when keepAlive are disabled this timeout is used to trigger peerUnreachable callbacks.
Return type: none
Parameters:
- none
Description: Disable the keep alive function.
Note:
Return type: none
Parameters:
- uint32 ui32RTT RTT value.
Description: Set the initial assumed RTT.
Note: InitialAssumedRTT, minimumRTT and maximumRTT are used together to calculate the retransmission timeout (RTO) of packets.
Return type: none
Parameters:
- uint32 ui32RTO RTO value.
Description: Set the maximum RTO.
Note: The value of the maximum RTO is zero by default. A value of zero means no maximum RTO
Return type: none
Parameters:
- uint32 ui32RTO RTO value.
Description: Set minimum RTO.
Return type: none
Parameters:
- float fRTOFactor RTO factor value.
Description: Set RTO factor.
Note: RTO factor and RTO constant are used in the calculation of the RTO for the packet according to this formula: _fSRTT + RTOConstant) * RTOFactor * (1 + pWrapper->getRetransmitCount()
Return type: none
Parameters:
- uint16 ui16RTOConstant RTO constant value.
Description: Set RTO constant.
Note: RTO factor and RTO constant are used in the calculation of the RTO for the packet according to this formula: _fSRTT + RTOConstant) * RTOFactor * (1 + pWrapper->getRetransmitCount()
Return type: none
Parameters:
- none
Description: Disables the the factor (1 + pWrapper->getRetransmitCount()) from RTO calculation.
Return type: none
Parameters:
- uint32 ui32WindowSize Window size value.
Description: Set maximum window Size.
Return type: none
Parameters:
- uint16 ui16SAckTransTO SACK transmit timeout value.
Description: Set SACK transmit timeout.
Return type: none
Parameters:
- uint32 ui32ConnectTO Connection timeout value.
Description: Set connection timeout.
Return type: none
Parameters:
- uint16 ui16UDPRecConTO Low level socket connection timeout value.
Description: Low level socket timeout at connection time.
Return type: none
Parameters:
- uint16 ui16UDPRecTO Low level socket connection timeout value.
Description: Low level socket timeout after connection is open.
Note: After connection is open.
Return type: int 0 Success, <0 Error code.
Parameters:
- const char *pszConfigFile Path to the configuration file.
Description: Different configuration files are defined for different type of networks. The application can call readConfigFile() and pass in the path to the configuration file that should be loaded.
Return type: none
Parameters:
- none
Description: When the behavior of a node is to be connected for some time, then disconnected for some time and then connected again and so on, the application may wish to reset the transmission counters upon reconnection so the communication won't suffer from the period of unreachability. The values reset with this function are estimated RTT and the transmit count and transmit timeout of the packets waiting for transmission in the unacknowledged packet queue.
Return type: none
Parameters:
- bool bEnableXMitLogging True for packet transmit logging.
Description: Enable or disable the packet transmit log.