| gclib 556 Communications API for Galil controllers and PLCs |

## ◆ GUtility()

GCLIB_DLL_EXPORTED GReturn GCALL GUtility | ( | GCon | g,
|  | GOption | request,
|  | GMemory | memory1,
|  | GMemory | memory2
| ) |  |

Provides read/write access to driver settings and convenience features based on the request variable.

Note
  The open source library, gclibo.h, has wrappers for most of these utilities.

Parameters

  g | Connection's handle.
  request | Defines the request. Input/Output and type of memory are implicit in the value of request. The following lists the supported request values.

- G_UTIL_TIMEOUT Read initial timeout value, as specified in GOpen() via `--timeout` switch.
  - `memory1` is output and must be an `unsigned short*`.
  - `memory2` is ignored, use null.
- G_UTIL_TIMEOUT_OVERRIDE See GTimeout(). Write/Read override timeout value.
  - `memory1` is input. If nonnull, value must be a `short*` holding the override, in milliseconds, for the timeout. Write `G_USE_INITIAL_TIMEOUT` to use initial timeout. If null, no write occurs.
  - `memory2` is output. If nonnul, value must be a `short*` which will be filled with the current override. `G_USE_INITIAL_TIMEOUT` indicates initial timeout used. If null, no read occurs. `memory2` is processed before 'memory1`.
- G_UTIL_VERSION See GVersion(). Returns the library version. A valid connection (g) is not necessary, i.e. g may be null.
  - `memory1` is output, and must be a `char*`. Data will be null terminated, even if the data must be truncated to do so.
  - `memory2` is input and must be an `unsigned int*` holding the length of the buffer in `memory1`.
- G_UTIL_INFO See GInfo(). Returns information about the connection.
  - `memory1` is output and must be a `char*`. Data will be null terminated, even if the data must be truncated to do so.
  - `memory2` is input and must be an `unsigned int*` holding the length of the buffer in `memory1`.
- G_UTIL_SLEEP See GSleep(). Platform-independent, non-busy, sleep. A valid connection (g) is not necessary, i.e. g may be null.
  - `memory1` is input and must be an `unsigned int*`, units are milliseconds.
  - `memory2` is ignored, use null.
- G_UTIL_ADDRESSES see GAddresses(). Provides a \n delimited listing of all available IP addresses, PCI addresses, and COM ports. A valid connection (g) is not necessary, i.e. g may be null. The suffix `-d` will be appended to each address to indicate these addresses are available via direct connection. See `G_UTIL_GCAPS_ADDRESSES` for addresses through gcaps.
  - `memory1` is output and must be a `char*`. Data will be null terminated, even if the data must be truncated to do so.
  - `memory2` is input and must be an `unsigned int*` holding the length of the buffer in `memory1`.
- G_UTIL_IPREQUEST see GIpRequests(). Listens and returns a \n delimited listing of Galil MAC addresses sending BOOT-P or DHCP requests. The function will listen, and block, for roughly 5 seconds. A valid connection (g) is not necessary, i.e. g may be null.
  - `memory1` is output and must be a `char*`. Data will be null terminated, even if the data must be truncated to do so.
  - `memory2` is input and must be an `unsigned int*` holding the length of the buffer in `memory1`.
- G_UTIL_ASSIGN see GAssign(). Provides a method to assign an IP address given a Galil MAC address. A valid connection (g) is not necessary, i.e. g may be null.
  - `memory1` is input and must be a `char*` containing the null terminated address that is to be assigned. e.g. `"192.168.0.43"`.
  - `memory2` is input and must be a `char*` containing the null terminated controller MAC address. e.g. `"00:50:4C:20:01:23"`.
- G_UTIL_DEVICE_INITIALIZE Provides a method to reinitialize a connection after a reset, e.g. an RS command. Depending on the device type, the appropriate commands will be sent to configure the communication bus for optimal performance.
  - `memory1` is ignored, use null.
  - `memory2` is ignored, use null.
- G_UTIL_PING Uses ICMP ping to determine if an IP address is reachable and assigned. A valid connection (g) is not necessary, i.e. g may be null.
  - `memory1` is input and must be a `char*` containing the null terminated address that is to be pinged. e.g. `"192.168.0.43"`.
  - `memory2` is output and must be an `int*`. The value will be set to zero if the ping times out, and nonzero if a ping reply is returned.
- G_UTIL_ERROR_CONTEXT More error detail for the last error on GCon, where available. The internal error message is cleared upon read.
  - `memory1` is output and must be a `char*`. Data will be null terminated, even if the data must be truncated to do so.
  - `memory2` is input and must be an `unsigned int*` holding the length of the buffer in `memory1`.

### The following request values are for use with a @ref gcaps server.

- G_UTIL_GCAPS_VERSION see GVersion(). Returns the gcaps server version. A valid connection (g) is not necessary, i.e. g may be null. This operation will connect to the server to determine the version.
  - `memory1` is output and must be a `char*`. Data will be null terminated, even if the data must be truncated to do so.
  - `memory2` is input and must be an `unsigned int*` holding the length of the buffer in `memory1`.
- G_UTIL_GCAPS_KEEPALIVE Provides a method for kicking the gcaps server. After a default period of 10 minutes of inactivity, gcaps will disconnect the gclib client. To prevent a disconnect, communicate with the hardware or call `G_UTIL_GCAPS_KEEPALIVE` within the timeout period to reset the timer. The current interval can be optionally read and overwritten, however, the keep alive signal is only sent if `memory1` and `memory2` are both null.
  - `memory1` is output. If nonnull, value must be an `unsigned int*` which will be filled with the current gcaps timeout, in ms.
  - `memory2` is input. If nonnull, value must be an `unsigned int*` holding the new gcaps timeout, in ms, for connection `g`.
- G_UTIL_GCAPS_ADDRESSES see GAddresses(). Provides a \n delimited listing of all available IP addresses, PCI addresses, and COM ports as available from the gcaps server. A valid connection (g) is not necessary, i.e. g may be null.
  - `memory1` is output and must be a `char*`. Data will be null terminated, even if the data must be truncated to do so.
  - `memory2` is input and must be an `unsigned int*` holding the length of the buffer in `memory1`.
- G_UTIL_GCAPS_IPREQUEST see GIpRequests(). Connects to gcaps and returns a \n delimited listing of Galil MAC addresses sending BOOT-P or DHCP requests. A valid connection (g) is not necessary, i.e. g may be null.
  - `memory1` is output and must be a `char*`. Data will be null terminated, even if the data must be truncated to do so.
  - `memory2` is input and must be an `unsigned int*` holding the length of the buffer in `memory1`.
- G_UTIL_GCAPS_ASSIGN see GAssign(). Provides a method to assign an IP address through gcaps given a Galil MAC address. A valid connection (g) is not necessary, i.e. g may be null.
  - `memory1` is input and must be a `char*` containing the null terminated address that is to be assigned. e.g. `"192.168.0.43"`.
  - `memory2` is input and must be a `char*` containing the null terminated controller MAC address. e.g. `"00:50:4C:20:01:23"`.
- G_UTIL_GCAPS_PING Uses ICMP ping to determine if an IP address is reachable and assigned. Ping sent from the gcaps server. A valid connection (g) is not necessary, i.e. g may be null.
  - `memory1` is input and must be a `char*` containing the null terminated address that is to be pinged. e.g. `"192.168.0.43"`.
  - `memory2` is output and must be an `int*`. The value will be set to zero if the ping times out, and nonzero if a ping reply is returned.

Parameters

  memory1 | An untyped pointer to data required for request. The data type is defined by the request variable.
  memory2 | An untyped pointer to data required for request. The data type is defined by the request variable.

Returns
  The success status or error code of the function. See gclib_errors.h for possible values.

See the following functions from gclibo, the open source portion, for implementation of several GUtility() requests.:

- GAddresses()
- GAssign()
- GInfo()
- GIpRequests()
- GSleep()
- GTimeout()
- GVersion()

Referenced by commands(), GAddresses(), GAssign(), GInfo(), GIpRequests(), GListServers(), GPublishServer(), GRemoteConnections(), GServerStatus(), GSetServer(), GSleep(), GTimeout(), GVersion(), and message().