Retrieves unsolicited data from a device and returns the data.

You can find the template for this subroutine in:

usrtm_unso.c

Syntax

void user_process_unsolicited_data(device_struct,

        data, start_address, sizeof_data, more,

        comm_status, status)

DEVICE_DATA *device_struct;

char *data;

ADDR_DATA *start_address;

int *sizeof_data;

int *more;

int *comm_status;

int *status;

Input Parameters

None

Output Parameters

device_struct

Is a pointer to the structure defining device data. DEVICE_DATA is a typedef to a structure defined in <inc_path/toolkit.h>.

The device_id field in this structure must be set.

data

Is the pointer to a buffer containing the data received.

If the devcomm has indicated support for quality data by setting support.unsolicited_quality_data to TOOLKIT_YES, then the following code illustrates how the buffer should be handled:

TOOLKIT_QUALDATA *pqual_data = (TOOLKIT_QUALDATA *)data;

pqual_data->sys_flags = 0;          //bits to be retained

pqual_data->sys_changed_mask = 0;   //indicate bits to be retained

pqual_data->user_flags = 0;         //bits to be retained

pqual_data->user_changed_mask = 0;  //indicate bits to be retained

data += sizeof (TOOLKIT_QUALDATA);

The data pointer now points to the area containing the point values. Any quality data changes indicated by the masks and values will be applied to all points serviced by the return buffer.

TOOLKIT_QUALDATA is a typedef to a structure defined in <inc_path/toolkit.h>.

start_address

Is a pointer to a structure that defines domain starting addresses in the device memory. ADDR_DATA is a typedef to a structure defined in <inc_path/toolkit.h>.

If standard addressing is used, the domain_index and domain_offset should be correctly set.

For custom addressing, the address string should be set.

sizeof_data

Contains the number of bytes of data (must be less than TOOLKIT_MAX_INTERNAL_BUFFER bytes).

more

Indicates whether there is more unsolicited data to be processed. Valid values are:

TRUE	More data needs processing
FALSE	All data has been sent

comm_status

Indicates whether a status of TOOLKIT_FAILURE occurred as a result of a communication failure. Valid values are:

TOOLKIT_SUCCESS	Failure is not due to communications failure.
TOOLKIT_FAILURE	Failure is due to communications failure.

status

Indicates whether the function successfully obtained all of the requested information. Valid values are:

TOOLKIT_SUCCESS	Function completed successfully.
TOOLKIT_FAILURE	Function did not complete successfully. Check comm_status to see if the failure was the result of a communication failure.

Return Value

None.

More information

Device Communications toolkit subroutines.

---