| gclib 329 Communications API for Galil controllers and PLCs |

All Data Structures Files Functions Variables Typedefs Macros Pages

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 a pointer to 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 pointer to a short which overrides 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 pointer to 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, e.g. g may be null. `memory1` is output, and must be a `GCStringOut`. Data will be null terminated, even if the data must be truncated to do so. `memory2` is input and must be a pointer to a `GSize` 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 `GCStringOut`. Data will be null terminated, even if the data must be truncated to do so. `memory2` is input and must be a pointer to a `GSize` holding the length of the buffer in `memory1`. `G_UTIL_SLEEP` See GSleep(). Platform-independent sleep. A valid connection (g) is not necessary, i.e. g may be null. `memory1` is input and must be a pointer to an unsigned int, units are milliseconds. `memory2` is ignored, use null. `G_UTIL_ADDRESSES` 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. `memory1` is output and must be a `GCStringOut`. Data will be null terminated, even if the data must be truncated to do so. `memory2` is input and must be a pointer to a `GSize` holding the length of the buffer in `memory1`. `G_UTIL_IPREQUEST` 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 `GCStringOut`. Data will be null terminated, even if the data must be truncated to do so. `memory2` is input and must be a pointer to a `GSize` holding the length of the buffer in `memory1`. `G_UTIL_ASSIGN` Provides a method to assign an IP address given a Galil MAC address and optionally a host NIC IP address. A valid connection (g) is not necessary, i.e. g may be null. The address to assign will be pinged to ensure its availability before the assign packet is sent. `G_GCLIB_UTILITY_IP_TAKEN` will be returned by GUtility() if the ping returns a response. `memory1` is input and must be a pointer to a `GCStringIn` containing the address that is to be assigned. e.g. `"192.168.0.43"` `memory2` is input and must be a pointer to a `GCStringIn` containing a comma-separated list with the controller's MAC address, followed by the IP address of the host's network interface to dispatch the assign packet. e.g. `"00:50:4C:20:01:23, 192.168.0.42"` If the host IP is omitted, the assign packet is sent out on all network interfaces. e.g. `"00:50:4C:20:01:23"` `G_UTIL_GCAPS_KEEPALIVE` Provides 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. `memory1` is output. If nonnull, value must be a pointer to a `GSIZE` which will be filled with the current gcaps timeout, in ms. `memory2` is input. If nonnull, value must be a pointer to a `GSIZE` which overrides the current gcaps timeout, in ms, for this connection. `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.
  memory1 | An untyped pointer to data type required for request.
  memory2 | An untyped pointer to data type required for request.

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

See source of gclibo.c for examples of `G_UTIL_TIMEOUT`, `G_UTIL_TIMEOUT_OVERRIDE`, `G_UTIL_VERSION`, `G_UTIL_INFO`, `G_UTIL_SLEEP`.

Except for serial ports, each line from `G_UTIL_ADDRESSES` will be of the form address, revision report (^R^V).

1 10.1.3.168, DMC30010 Rev 1.2d
2 GALILPCI1, DMC1826 Rev 1.1a
3 COM7
4 COM8

See GAddresses() for an example of `G_UTIL_ADDRESSES`.

Note
  Linux/OS X users must be root to use G_UTIL_IPREQUEST and have UDP access to bind and listen on port 67.

Each line from `G_UTIL_IPREQUEST` will be of the form model, serial_number, mac.

1 DMC4000, 291, 00:50:4c:20:01:23
2 DMC30000, 4184, 00:50:4c:40:10:58
//example for getting controllers requesting IPs
char buf[1024];
GSize len = sizeof(buf);
GUtility(0, G_UTIL_IPREQUEST, buf, &len);
cout << buf << "\n";

Note
  Linux users must be root to use G_UTIL_ASSIGN and have UDP access to send on port 68.

//example of assigning an IP address.
GUtility(0, G_UTIL_ASSIGN, "10.1.3.178", "00:50:4c:40:10:58"); //Assign 10.1.3.178 TO 00:50:4c:40:10:58

Referenced by GAddresses(), GAssign(), GInfo(), GIpRequests(), GSleep(), GTimeout(), and GVersion().