Connection

Discover available controllers and open connections More...

Functions
GCLIB_DLL_EXPORTED GReturn GCALL	GOpen (GCStringIn address, GCon *g)
	Open a connection to a Galil Controller.
GCLIB_DLL_EXPORTED GReturn GCALL	GClose (GCon g)
	Closes a connection to a Galil Controller.
GCLIB_DLL_EXPORTED GReturn GCALL	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_DLL_EXPORTED GReturn GCALL	GInfo (GCon g, GCStringOut info, GSize info_len)
	Uses GUtility() and G_UTIL_INFO to provide a useful connection string.
GCLIB_DLL_EXPORTED GReturn GCALL	GTimeout (GCon g, short timeout_ms)
	Uses GUtility() and G_UTIL_TIMEOUT_OVERRIDE to set the library timeout.
GCLIB_DLL_EXPORTED GReturn GCALL	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_DLL_EXPORTED GReturn GCALL	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.

Function Documentation

GOpen()

GCLIB_DLL_EXPORTED GReturn GCALL GOpen	(	GCStringIn	address,
		GCon *	g )

Open a connection to a Galil Controller.

Parameters

address	Null-terminated address 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_DLL_EXPORTED GReturn GCALL GClose

(

GCon

g

)

Closes a connection to a Galil Controller.

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. The latter can occur, for example, if a call to GRead() times out and the process exits without calling GClose(). In this case, GRead() still has an outstanding asynchronous read pending. GClose() will terminate this operation allowing the process to exit correctly.

Parameters

g	Connection's handle.

Returns

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

See x_examples.cpp for an example.

GAddresses()

GCLIB_DLL_EXPORTED GReturn GCALL 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.

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.

See x_examples.cpp for an example.

GInfo()

GCLIB_DLL_EXPORTED GReturn GCALL GInfo	(	GCon	g,
		GCStringOut	info,
		GSize	info_len )

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

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

See x_examples.cpp for an example.

GTimeout()

GCLIB_DLL_EXPORTED GReturn GCALL GTimeout	(	GCon	g,
		short	timeout_ms )

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

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.

See x_gcommand.cpp and x_gread_gwrite.cpp for examples.

GIpRequests()

GCLIB_DLL_EXPORTED GReturn GCALL 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.

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

See x_examples.cpp for an example.

GAssign()

GCLIB_DLL_EXPORTED GReturn GCALL 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.

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.

See x_examples.cpp for an example.