ConnectionFlags Method

Eth32ConnectionFlag ConnectionFlags(int reset)

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 method retrieves the flags for this connection to the device. If instructed to do so, the method also clears all of the flags for this connection to zero immediately after retrieving them.

Parameters

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

Return Value

This method returns a Eth32ConnectionFlag enumerator type. The return value may be made up of any combination (that is, a bitwise or) of the following enumerator flags. Each flag indicates which kind of data had to be discarded due to a full queue.

  • Eth32ConnectionFlag.None - If the return value equals this exactly, then no flags were set.

  • Eth32ConnectionFlag.Response - Response to a query for information (for example InputByte Method).

  • Eth32ConnectionFlag.DigitalEvent - Digital event notification.

  • Eth32ConnectionFlag.AnalogEvent - Analog event notification.

  • Eth32ConnectionFlag.CounterEvent - Counter event (rollover or threshold) notification.

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.

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 method. 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 ResetDevice Method 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 dev = new Eth32();
Eth32ConnectionFlag flags;

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

	// Retrieve the connection flags for this connection and 
	// simultaneously clear them to zero.
	flags=dev.ConnectionFlags(1);
	
	// See which flags are set
	if((flags & Eth32ConnectionFlag.Response)==Eth32ConnectionFlag.Response)
	{
		// The device ran out of queue space at some point
		// when it was trying to respond to a query for information.
	}
	
	if((flags & Eth32ConnectionFlag.DigitalEvent)==Eth32ConnectionFlag.DigitalEvent)
	{
		// Some digital event data was lost due to running out 
		// of queue space.
	}
	
	// and so on

	
	// Or, to check whether any flags at all are set:
	if(flags == Eth32ConnectionFlag.None)
	{
		// No flags whatsoever are set
	}
	else
	{
		// At least one flag is set
	}
}
catch (Eth32Exception e)
{
	// Handle Eth32 errors here
}
        
See Also

VerifyConnection Method