Gocator API
 All Classes Files Functions Variables Typedefs Macros Groups Pages
GoSystem Class Reference

Description

Represents a system of Gocator devices.

During construction, a GoSystem object uses Gocator Discovery Protocol to locate devices. Subsequently, the list of detected devices can be accessed using GoSystem_SensorCount and GoSystem_SensorAt.

Immediately after construction, all sensor objects are in the online state. This state indicates that a sensor has been detected, but that the client has not yet established a control connection to the sensor. The only sensor functions than can be used in this state are GoSensor_State, GoSensor_Address, and GoSensor_SetAddress.

Because Gocator Discovery Protocol works across subnets, but Gocator Control Protocol does not, it is possible for a sensor to be successfully detected but for subequent connection attempts to fail. In this case, the GoSensor_SetAddress function can be used to reconfigure the sensor to operate on the same subnet as the client.

If the client and device are configured to operate on the same subnet, the GoSystem_Connect or GoSensor_Connect functions can be used to establish control connections.

See also
GoSystem_Construct, GoSystem_Connect, GoSensor_State, GoSensor_Address, GoSensor_SetAddress.

Inherits kObject.

Public Member Functions

kStatus GoSystem_Cancel (GoSystem system)
 Aborts ongoing sensor communication. More...
 
kStatus GoSystem_ClearData (GoSystem system)
 Clears any buffered data messages. More...
 
kStatus GoSystem_ClearHealth (GoSystem system)
 Clears any buffered health messages. More...
 
kStatus GoSystem_Connect (GoSystem system)
 Establishes control connections to all sensors. More...
 
kStatus GoSystem_Construct (GoSystem *system, kAlloc allocator)
 Constructs a GoSystem object. More...
 
kSize GoSystem_DataCapacity (GoSystem system)
 Reports that maximum amount of memory that can be used to buffer received data messages. More...
 
kStatus GoSystem_Disconnect (GoSystem system)
 Terminates control connections to all sensors. More...
 
kStatus GoSystem_EnableData (GoSystem system, kBool enable)
 Establishes data connections to all sensors currently in the ready or running states. More...
 
kStatus GoSystem_FindSensor (GoSystem system, k32u id, GoSensor *sensor)
 Gets the sensor object with the specified device id (serial number). More...
 
kStatus GoSystem_GetEncoder (GoSystem system, k64s *encoder)
 Gets the current encoder value from the sensor network. More...
 
kStatus GoSystem_GetTimeStamp (GoSystem system, k64u *time)
 Gets the current time stamp from the sensor network. More...
 
kBool GoSystem_HasChanges (GoSystem system)
 Reports whether the system has changes that require a refresh. More...
 
kVersion GoSystem_ProtocolVersion ()
 Reports the Gocator Protocol version implemented by this library. More...
 
kStatus GoSystem_ReceiveData (GoSystem system, GoDataSet *data, k64u timeout)
 Receives a set of sensor data messages. More...
 
kStatus GoSystem_ReceiveHealth (GoSystem system, GoDataSet *data, k64u timeout)
 Receives a set of sensor health messages. More...
 
kStatus GoSystem_Refresh (GoSystem system)
 Updates client state to reflect any changes that have occurred in the sensor network. More...
 
kStatus GoSystem_Reset (GoSystem system, kBool wait)
 Reboots all connected sensors. More...
 
GoSensor GoSystem_SensorAt (GoSystem system, kSize index)
 Gets the sensor object at the specified index. More...
 
kSize GoSystem_SensorCount (GoSystem system)
 Gets the number of sensors in the system. More...
 
kStatus GoSystem_SetDataCapacity (GoSystem system, kSize capacity)
 Sets the maximum amount of memory that can be used to buffer received data messages. More...
 
kStatus GoSystem_SetDataHandler (GoSystem system, GoDataFx function, kPointer receiver)
 Sets a callback function that can be used to receive sensor data messages asychronously. More...
 
kStatus GoSystem_SetHealthHandler (GoSystem system, GoDataFx function, kPointer receiver)
 Sets a callback function that can be used to receive sensor health messages asychronously. More...
 
kStatus GoSystem_Start (GoSystem system)
 Starts all sensors that are currently in the ready state. More...
 
kStatus GoSystem_StartAlignment (GoSystem system)
 Starts alignment for sensor in the ready state. More...
 
kStatus GoSystem_StartExposureAutoSet (GoSystem system)
 Starts exposure auto set for sensor(s) in the ready state. More...
 
kStatus GoSystem_Stop (GoSystem system)
 Stops all connected sensors. More...
 

Member Function Documentation

kStatus GoSystem_Cancel ( GoSystem  system)

Aborts ongoing sensor communication.

This method asynchronously aborts ongoing communication; the next time that any I/O operation blocks for an extended period of time, it will be terminated. This method is thread-safe.

In order to resume communication, call GoSystem_Refresh or GoSystem_Connect.

Parameters
systemGoSystem object.
Returns
Operation status.
kStatus GoSystem_ClearData ( GoSystem  system)

Clears any buffered data messages.

When stopping and then restarting a system, it may be desirable to ensure that no messages from the previous session remain in any buffers. The GoSystem_ClearData function closes any open data channels, destroys any received messages, and then reopens data channels.

Parameters
systemGoSystem object.
Returns
Operation status.
kStatus GoSystem_ClearHealth ( GoSystem  system)

Clears any buffered health messages.

Parameters
systemGoSystem object.
Returns
Operation status.
kStatus GoSystem_Connect ( GoSystem  system)

Establishes control connections to all sensors.

A control connection is required before calling any sensor function except GoSensor_State, GoSensor_Address, or GoSensor_SetAddress.

Parameters
systemGoSystem object.
Returns
Operation status.
kStatus GoSystem_Construct ( GoSystem system,
kAlloc  allocator 
)

Constructs a GoSystem object.

During construction, a GoSystem object uses Gocator Discovery Protocol to locate sensors. The list of detected sensors can be accessed using the GoSystem_SensorCount and GoSystem_SensorAt functions.

Parameters
systemReceives constructed system object.
allocatorMemory allocator (or kNULL for default)
Returns
Operation status.
kSize GoSystem_DataCapacity ( GoSystem  system)

Reports that maximum amount of memory that can be used to buffer received data messages.

Parameters
systemGoSystem object.
Returns
Data queue capacity, in bytes.
See also
GoSystem_SetDataCapacity
kStatus GoSystem_Disconnect ( GoSystem  system)

Terminates control connections to all sensors.

Parameters
systemGoSystem object.
Returns
Operation status.
kStatus GoSystem_EnableData ( GoSystem  system,
kBool  enable 
)

Establishes data connections to all sensors currently in the ready or running states.

Data connections are not automatically established when sensor control connection are established. Use this function (or GoSensor_EnableData) to enable/disable data connections.

Parameters
systemGoSystem object.
enablekTRUE to enable data connections; kFALSE to disable.
Returns
Operation status.
See also
GoSensor_EnableData
kStatus GoSystem_FindSensor ( GoSystem  system,
k32u  id,
GoSensor sensor 
)

Gets the sensor object with the specified device id (serial number).

Parameters
systemGoSystem object.
idDevice identifier.
sensorRecieves sensor object.
Returns
Operation status (kERROR_NOT_FOUND if sensor not found).
See also
GoSystem_SensorCount, GoSystem_SensorAt
kStatus GoSystem_GetEncoder ( GoSystem  system,
k64s *  encoder 
)

Gets the current encoder value from the sensor network.

Parameters
systemGoSystem object.
encoderReceives current encoder value (ticks).
Returns
Operation status (kERROR_NOT_FOUND if no sensors available).
See also
GoSystem_GetTime
kStatus GoSystem_GetTimeStamp ( GoSystem  system,
k64u *  time 
)

Gets the current time stamp from the sensor network.

Parameters
systemGoSystem object.
timeReceives current time stamp(microseconds).
Returns
Operation status (kERROR_NOT_FOUND if no sensors available).
See also
GoSystem_GetEncoder
kBool GoSystem_HasChanges ( GoSystem  system)

Reports whether the system has changes that require a refresh.

Sensors can undergo autonomous state changes that require client state to be refreshed (e.g. sensor goes offline). The GoSystem_HasChanges function can be used to determine if such changes have occurred.

The GoSystem_HasChanges function does not perform communcation, and consequently, will not require the caller to block for a long duration. If changes are detected, the GoSystem_Refresh function can be called to resolve the changes.

This method is thread-safe.

Parameters
systemGoSystem object.
Returns
kTRUE if the system has changes.
kVersion GoSystem_ProtocolVersion ( )

Reports the Gocator Protocol version implemented by this library.

A Gocator Protocol version number has a major component and a minor component. If the major version implemented by this library is the same as the major version implemented by a sensor device, then communcation can proceed. Otherwise, the sensor should be upgraded or a newer version of this library should be obtained. Sensors with incompatible major versions will be reported as being in the incompatible state upon connection.

If major versions match, but the minor version implemented by this library is lower than the minor version implemented by the sensor, then some sensor features will not be accessible through this library.

If major versions match, but the minor version implemented by this library is higher than the minor version implemented by the sensor, then some features exposed by this library may be unimplemented by the sensor.

This method is thread-safe.

Returns
Protocol version implemented by this library.
See also
GoSensor_ProtocolVersion, GoSensor_State
kStatus GoSystem_ReceiveData ( GoSystem  system,
GoDataSet data,
k64u  timeout 
)

Receives a set of sensor data messages.

Sensor data messages can be received synchronously using this function or asynchronously by registering a callback with the GoSystem_SetDataHandler function.

Parameters
systemGoSystem object.
dataSet of sensor data messages.
timeoutDuration to wait for messages, in microseconds.
Returns
Operation status.
See also
GoSystem_SetDataHandler, GoSystem_SetDataCapacity, GoSystem_EnableData
kStatus GoSystem_ReceiveHealth ( GoSystem  system,
GoDataSet data,
k64u  timeout 
)

Receives a set of sensor health messages.

Sensor health messages can be received synchronously using this function or asynchronously by registering a callback with the GoSystem_SetHealthHandler function.

Parameters
systemGoSystem object.
dataSet of sensor health messages.
timeoutDuration to wait for messages, in microseconds.
Returns
Operation status.
See also
GoSystem_SetHealthHandler
kStatus GoSystem_Refresh ( GoSystem  system)

Updates client state to reflect any changes that have occurred in the sensor network.

Sensors can undergo autonomous state changes that require client state to be refreshed (e.g. sensor goes offline). The GoSystem_Refresh function resynchronizes client state with the current state of the sensor network.

Calling this function may destroy or modify local sensor objects. The GoSystem_HasChanges function can be used prior to calling GoSystem_Refresh, to determine whether a refresh is needed.

Parameters
systemGoSystem object.
Returns
Operation status.
kStatus GoSystem_Reset ( GoSystem  system,
kBool  wait 
)

Reboots all connected sensors.

Parameters
systemGoSystem object.
waitkTRUE to wait for reboot complete; kFALSE to return immediately.
Returns
Operation status.
GoSensor GoSystem_SensorAt ( GoSystem  system,
kSize  index 
)

Gets the sensor object at the specified index.

Parameters
systemGoSystem object.
indexSensor index.
Returns
Sensor object.
See also
GoSystem_SensorCount
kSize GoSystem_SensorCount ( GoSystem  system)

Gets the number of sensors in the system.

Parameters
systemGoSystem object.
Returns
Count of sensors in the system.
See also
GoSystem_SensorAt
kStatus GoSystem_SetDataCapacity ( GoSystem  system,
kSize  capacity 
)

Sets the maximum amount of memory that can be used to buffer received data messages.

Received data messages are enqueued until they are accepted by the caller. This function determines the maximum size, in bytes, of enqueued messages. The default maximum size is 50 MB.

Parameters
systemGoSystem object.
capacityData queue capacity, in bytes.
Returns
Operation status.
See also
GoSystem_DataCapacity
kStatus GoSystem_SetDataHandler ( GoSystem  system,
GoDataFx  function,
kPointer  receiver 
)

Sets a callback function that can be used to receive sensor data messages asychronously.

Sensor data messages can be received synchronously using the GoSystem_ReceiveData function or asynchronously by registering a callback function. If a callback function is registered, a background thread will be created to perform notifications.

To unregister a previously-registered data handler, call this function using kNULL in place of the callback function argument.

Parameters
systemGoSystem object.
functionData callback function (or kNULL to unregister).
receiverReceiver argument for callback.
Returns
Operation status.
See also
GoDataFx, GoSystem_ReceiveData, GoSystem_SetDataCapacity, GoSystem_EnableData
kStatus GoSystem_SetHealthHandler ( GoSystem  system,
GoDataFx  function,
kPointer  receiver 
)

Sets a callback function that can be used to receive sensor health messages asychronously.

Sensor health messages can be received synchronously using the GoSystem_ReceiveHealth function or asynchronously by registering a callback function. If a callback function is registered, a background thread will be created to perform notifications.

To unregister a previously-registered health handler, call this function using kNULL in place of the callback function argument.

Parameters
systemGoSystem object.
functionHealth callback function (or kNULL to unregister).
receiverReceiver argument, passed to callback.
Returns
Operation status.
See also
GoDataFx, GoSystem_ReceiveHealth, GoSystem_SetDataCapacity, GoSystem_EnableData
kStatus GoSystem_Start ( GoSystem  system)

Starts all sensors that are currently in the ready state.

Parameters
systemGoSystem object.
Returns
Operation status.
See also
GoSystem_Stop, GoSensor_Start, GoSensor_Stop
kStatus GoSystem_StartAlignment ( GoSystem  system)

Starts alignment for sensor in the ready state.

Parameters
systemGoSystem object.
Returns
Operation status.
See also
GoSystem_Stop, GoSensor_Start, GoSensor_Stop
kStatus GoSystem_StartExposureAutoSet ( GoSystem  system)

Starts exposure auto set for sensor(s) in the ready state.

Parameters
systemGoSystem object.
Returns
Operation status.
See also
GoSystem_Stop, GoSensor_Align, GoSensor_Stop
kStatus GoSystem_Stop ( GoSystem  system)

Stops all connected sensors.

Parameters
systemGoSystem object.
Returns
Operation status.
See also
GoSystem_Start, GoSensor_Start, GoSensor_Stop

The documentation for this class was generated from the following file: