eth32_connection_flags

int eth32_connection_flags(eth32 handle, int reset, int *flags);

Summary

The ETH32 device maintains several flag bits for each individual active TCP/IP connection. The flags indicate conditions that are (or were) present for that connection. Currently, these flags are used to indicate whether any data that needed to be sent to your application from the ETH32 device had to be discarded due to lack of queue space. This function retrieves the flags for this connection to the device. If instructed to do so, the function also clears all of the flags for this connection to zero immediately after retrieving them.

Parameters

  • handle - The value returned by the eth32_open function.

  • reset - If nonzero, specifies that the flags for this connection should be reset to zero immediately after retrieving them.

  • flags - Pointer to a variable which will receive the current flags value for this connection. See the remarks below for a list of the individual flags that can make up this value.

Return Value

This function returns zero on success and a negative error code on failure. Please see the Error Codes section for possible error codes.

Remarks

To understand the role of the connection flags, consider the following example. Suppose that digital events are enabled on port 0, bit 0 for your connection to the ETH32. Now suppose that port 0, bit 0 begins pulsing rapidly, generating a steady stream of event notifications. Finally, suppose that the connection to your application is having trouble (losing packets, etc). Due to the nature of TCP/IP, the event notifications must be retained in the queue of the ETH32 device until a TCP/IP acknowledgement for them has been received from the PC (in case they need to be retransmitted). If the TCP/IP acknowledgements do not come promptly and the events keep occurring, the queue will eventually fill up and the ETH32 device will be forced to simply discard any new event notifications. Although this scenario is undesirable and should be avoided, if it does happen, it is helpful for your application to be able to detect that it happened and that data was lost. The flags keep track of this individually for each TCP/IP connection (that is, a full queue on one connection will not affect flags on another). Note that the flags are informational only - they do not affect the behavior of the device.

The flags value can be made up of a bitwise OR of any or all of the following individual flags. Each flag indicates which kind of data had to be discarded due to a full queue.

  • CONN_FLAG_RESPONSE - Response to a query for information (for example eth32_input_byte).

  • CONN_FLAG_DIGITAL_EVENT - Digital event notification.

  • CONN_FLAG_ANALOG_EVENT - Analog event notification.

  • CONN_FLAG_COUNTER_EVENT - Counter event (rollover or threshold) notification.

Once a flag is set, it will remain set until it is reset back to zero by passing a nonzero number to the reset parameter of this function. In this case, the flags will only be reset to zero if the connection has enough space to queue up the reply data. In other words, the flags will not be lost if the response itself is unable to be queued.

The connection flags for new connections always start out as zero. When the eth32_reset function is called, the flags for the connection it was received on are cleared, but the flags for any other active connections are not affected.

Example
eth32 handle;
int result;
int flags;

// .... Your code that establishes a connection here

// Retrieve the connection flags for this connection and 
// simultaneously clear them to zero.
result=eth32_connection_flags(handle, 1, &flags);
if(result)
{
	// Handle error
}

// See which flags are set
if(flags & CONN_FLAG_RESPONSE)
{
	// The device ran out of queue space at some point
	// when it was trying to respond to a query for information.
}

if(flags & CONN_FLAG_DIGITAL_EVENT)
{
	// Some digital event data was lost due to running out 
	// of queue space.
}

// and so on
         
See Also

eth32_verify_connection