| gclib 2.4.1 Galil Communications Library

Loading...
Searching...
No Matches
Functions
Connection
C (Legacy)

Discover available controllers and open connections. More...

## Functions
GCLIB_DEPRECATED GReturn | GOpen (GCStringIn connection_string, GCon *g)
| Open a connection to a Galil Controller.
GCLIB_DEPRECATED GReturn | GClose (GCon g)
| Closes a connection to a Galil Controller.
GCLIB_DEPRECATED GReturn | GAddresses (GCStringOut addresses, GSize addresses_len)
| Uses GUtility(), G_UTIL_GCAPS_ADDRESSES or G_UTIL_ADDRESSES to provide a listing of all available connection addresses.
GCLIB_DEPRECATED GReturn | GInfo (GCon g, GCStringOut info, GSize info_len)
| Uses GUtility() and G_UTIL_INFO to provide a useful connection string.
GCLIB_DEPRECATED GReturn | GTimeout (GCon g, short timeout_ms)
| Uses GUtility() and G_UTIL_TIMEOUT_OVERRIDE to set the library timeout.
GCLIB_DEPRECATED GReturn | GIpRequests (GCStringOut requests, GSize requests_len)
| Uses GUtility(), G_UTIL_GCAPS_IPREQUEST or G_UTIL_IPREQUEST to provide a list of all Galil controllers requesting IP addresses via BOOT-P or DHCP.
GCLIB_DEPRECATED GReturn | GAssign (GCStringIn ip, GCStringIn mac)
| Uses GUtility(), G_UTIL_GCAPS_ASSIGN or G_UTIL_ASSIGN to assign an IP address over the Ethernet to a controller at a given MAC address.

## Detailed Description

Discover available controllers and open connections.

## Function Documentation

## ◆ GOpen()

GCLIB_DEPRECATED GReturn GOpen | ( | GCStringIn | connection_string,
|  | GCon * | g )

Open a connection to a Galil Controller.

Deprecated
  This function is part of the deprecated C (Legacy) API, which will be removed in a future release. Use gclib_open() instead.

Parameters

  connection_string | Null-terminated connection string. See table below.
  g | Pointer to user's GCon variable. On success, the library will fill the user's variable with the handle to use for the rest of the connection. A valid g value is nonzero.

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

address switch | Meaning | Arguments (default), other options | Examples
--- | --- | --- | ---
--address | Simple address to hardware | IP address, PCI, COM port | --address COM1
-a | shorthand for --address | See Address Ranges below | -a GALILPCI1
{no switch} | --address is implicit for any lone token |  | 192.168.0.42
--baud | Baud rate | (115200), valid baud... | COM2 --baud 19200
-b | shorthand for --baud |  | COM3 -b 38400
--command | Command-and-response socket protocol | (TCP), UDP | 192.168.0.42 --command TCP
-c | shorthand for --command |  | 192.168.0.42 -c UDP
--direct | Connect directly to hardware instead of via gcaps |  | -a GALILPCI2 --direct
-d | shorthand for --direct |  | GALILPCI2 -d
--subscribe | Subscribe to messages, data records, and/or interrupts | (NONE), MG, DR, EI, ALL | 192.168.0.42 --subscribe MG
-s | shorthand for --subscribe |  | 192.168.0.42 -s DR -s EI
--timeout | timeout in ms | (5000), 0-65535 | 192.168.0.42 --timeout 5000
-t | shorthand for --timeout |  | GALILPCI2 -t 500
--unsolicited | Unsolicited socket protocol | (UDP), NONE | 192.168.0.42 --unsolicited NONE
-u | shorthand for --unsolicited |  | 192.168.1.42 -u UDP
The following address switches are deprecated and will be unavailable starting July 1st, 2020.
--p1 | Primary port for command-and-response traffic | (23), valid port number | 192.168.0.42 --p1 5000
--p2 | Secondary port for unsolicited traffic | (60007), valid port number | 192.168.0.42 --p2 5000

Operating System | Address Range | Notes
--- | --- | ---
Windows | COM1 - COM256 | RS232 and USB-to-serial
Linux | /dev/ttyS0 - /dev/ttyS255 | RS232
Linux | /dev/ttyUSB0 - /dev/ttyUSB255 | USB-to-serial, e.g. DMC-4103
Windows | GALILPCI1 - GALILPCI8 | PCI
Linux | /dev/galilpci0 - /dev/galilpci7 | PCI

When connecting to a network device, if the command-and-response socket is opened successfully but the unsolicited socket fails, GOpen() will still complete successfully. This allows connection to a Galil controller when only one Ethernet handle is available. Unsolicited traffic will not be accessible in this case.

## ◆ GClose()

GCLIB_DEPRECATED GReturn GClose | ( | GCon | g | ) |

Closes a connection to a Galil Controller.

Deprecated
  This function is part of the deprecated C (Legacy) API, which will be removed in a future release. Use gclib_close() instead.

Attention
  gclib requires that GClose() be called whenever a program is finished with a controller. This includes when a program closes. A rule of thumb is that for every GOpen() call on a given connection, a GClose() call should be found on every code path. Failing to call GClose() may cause controller resources to not be released or can hang the process if there are outstanding asynchronous operations.

Parameters

  g | Connection's handle.

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

## ◆ GAddresses()

GCLIB_DEPRECATED GReturn GAddresses | ( | GCStringOut | addresses,
|  | GSize | addresses_len )

Uses GUtility(), G_UTIL_GCAPS_ADDRESSES or G_UTIL_ADDRESSES to provide a listing of all available connection addresses.

Deprecated
  This function is part of the deprecated C (Legacy) API, which will be removed in a future release. Use gclib_addresses() instead.

Note
  Serial ports are listed, e.g. COM1. Upon open, it may be necessary to specify a baud rate for the controller, e.g. --baud 19200. Default baud is 115200. See GOpen().

Parameters

  addresses | Buffer to hold the output string. Buffer will be null terminated, even if the data must be truncated to do so. See below for more information.
  addresses_len | Length of buffer.

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

If gcaps is available, the listing will come from the server via G_UTIL_GCAPS_ADDRESSES. In the absence of the server, gclib will use G_UTIL_ADDRESSES to generate the list.

- Ethernet controllers will be listed as ip_address, revision_report, network_adapter_name, network_adapter_ip_address. If an IP address is unreachable via ping, the address will be in parentheses.
- PCI controllers will be listed by their identifier, e.g. GALILPCI1.
- Serial ports will be listed by their identifier, e.g. COM1.

    10.1.3.91, DMC4020 Rev 1.2e, LAN, 10.1.3.10
    192.168.0.63, DMC4040 Rev 1.2f, Static, 192.168.0.41
    (192.0.0.42), RIO47102 Rev 1.1j, Static, 192.168.0.41
    GALILPCI1
    COM1
    COM2

Note
  GAddresses() will take up to 1 second to look for gcaps.

## ◆ GInfo()

GCLIB_DEPRECATED GReturn GInfo | ( | GCon | g,
|  | GCStringOut | info,
|  | GSize | info_len )

Uses GUtility() and G_UTIL_INFO to provide a useful connection string.

Deprecated
  This function is part of the deprecated C (Legacy) API, which will be removed in a future release. Use gclib_address(), gclib_revision_information(), and gclib_serial_number() instead.

Parameters

  g | Connection's handle.
  info | Buffer to hold the output string. Buffer will be null terminated, even if the data must be truncated to do so.
  info_len | Length of buffer.

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

The response is address, revision_report, serial_number. For example:

    COM2, RIO47102 Rev 1.1j, 37290

## ◆ GTimeout()

GCLIB_DEPRECATED GReturn GTimeout | ( | GCon | g,
|  | short | timeout_ms )

Uses GUtility() and G_UTIL_TIMEOUT_OVERRIDE to set the library timeout.

Deprecated
  This function is part of the deprecated C (Legacy) API, which will be removed in a future release.

Parameters

  g | Connection's handle.
  timeout_ms | The value to be used for the timeout. Use G_USE_INITIAL_TIMEOUT to set the timeout back to the initial GOpen() value, --timeout.

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

## ◆ GIpRequests()

GCLIB_DEPRECATED GReturn GIpRequests | ( | GCStringOut | requests,
|  | GSize | requests_len )

Uses GUtility(), G_UTIL_GCAPS_IPREQUEST or G_UTIL_IPREQUEST to provide a list of all Galil controllers requesting IP addresses via BOOT-P or DHCP.

Deprecated
  This function is part of the deprecated C (Legacy) API, which will be removed in a future release. Use gclib_ip_requests() instead.

Parameters

  requests | The buffer to hold the list of requesting controllers. Data will be null terminated, even if the data must be truncated to do so. See below for more information.
  requests_len | The length of the requests buffer.

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

GIpRequests() will block up to 5 seconds while listening for requests.

If gcaps is available, the listing will come from the server via G_UTIL_GCAPS_IPREQUEST. In the absence of the server, gclib will use G_UTIL_IPREQUEST to generate the list. GIpRequests() will take up to 1 second to look for gcaps. When not using gcaps, Linux/OS X users must be root to use GIpRequests() and have UDP access to bind and listen on port 67.

Each line of the returned data will be of the form model, serial_number, MAC_address, network_adapter_name, network_adapter_ip_address, remembered_ip_assignment. See GAssign() for more infomation about remembered IP assignments. The following is an example output.

    DMC2000, 34023, 00:50:4C:00:84:E7, enp5s0, 192.168.42.92, 192.168.42.200
    DMC2105, 7, 00:50:4C:58:00:07, enp5s0, 192.168.42.92, 0.0.0.0
    DMC2105, 13, 00:50:4C:58:00:0D, enp5s0, 192.168.42.92, 0.0.0.0

## ◆ GAssign()

GCLIB_DEPRECATED GReturn GAssign | ( | GCStringIn | ip,
|  | GCStringIn | mac )

Uses GUtility(), G_UTIL_GCAPS_ASSIGN or G_UTIL_ASSIGN to assign an IP address over the Ethernet to a controller at a given MAC address.

Deprecated
  This function is part of the deprecated C (Legacy) API, which will be removed in a future release. Use gclib_assign_ip() instead.

Parameters

  ip | The null-terminated ip address to assign. The hardware should not yet have an IP address.
  mac | The null-terminated MAC address of the hardware.

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

On Linux and Mac, the desired IP address will be pinged prior to the assignment. If the ping is returned, GAssign() will return G_GCLIB_UTILITY_IP_TAKEN.

If gcaps is available, the assign will be performed from the server via G_UTIL_GCAPS_ASSIGN. gcaps will remember the assignment and will automatically assign the desired IP address should the controller ever request one again, e.g. after a controller master reset. To clear the remembered IP address from gcaps, call GAssign() with a blank string in place of the ip address. To remove all remembered ip addresses, specfify a blank string for the mac address.

In the absence of the server, gclib will use G_UTIL_ASSIGN to assign. GAssign() will take up to 1 second to look for gcaps. When not using gcaps, Linux/OS X users must be root to use GAssign() and have UDP access to send on port 68.