The first thing your application must do in order to use the ETH32 device is create a connection to the device. A connection must be made before any other functions or members of the API are called, unless otherwise specified.
After your application has finished using the ETH32 device, it should be sure to disconnect the connection to the ETH32 device. The ETH32 device has a relatively small number of simultaneous connections available, so leaving a connection open unnecessarily could in some cases prevent other applications from opening a connection. When your application exits, the operating system will automatically close any open connections. However, Visual Basic 6 programmers should see the Remarks section of the Disconnect Method for precautions.
You may connect and disconnect from the device as often as you'd like. The decision of when to do this should be made depending on the type of application you are creating. If your application only performs an operation on the ETH32 once in a while and has long periods of inactivity, you may decide to connect and disconnect each time. However, most applications will simply connect once and remain connected until the application exits or it is completely finished using the ETH32. That is the simplest approach in most cases.
If at any point in your code, you have a connection but would like to verify that data is still being transferred over the connection properly, you may do so using the "verify connection" function. This sends a small command over your existing connection, which the ETH32 device will simply return without performing any other operation. If for any reason the data isn't returned within the timeout period, the function will return or generate an error.
In .NET languages as well as Visual Basic 6, the class provides a Connected property to indicate whether the object currently holds a connection to an ETH32 device. This property does not actually verify the integrity of the connection. When true, it simply indicates that a connection has been successfully created and that Disconnect has not been called since then. This is often useful during application shutdown in determining whether the Disconnect method needs to be called in order to free resources.
Note that the ETH32 libraries allow your application to simultaneously use as many ETH32 devices as resources allow. In certain circumstances, you may even want to open two connections to the same ETH32 device from within one application.
Almost all of the resources of the ETH32 are shared among its connections and are not affected by connections being opened or closed. So, for example, opening a new connection to the ETH32 does not affect the direction registers of any ports. One notable exception is that each connection individually selects which event notifications it will receive. Therefore, each new connection starts out with all event notifications disabled.
Task | C / C++ | .NET Languages | Visual Basic 6 |
---|---|---|---|
Open connection | eth32_open | Connect Method | Connect Method |
Verify connection | eth32_verify_connection | VerifyConnection Method | VerifyConnection Method |
Determine if object is connected | Connected Property | Connected Property | |
Disconnect | eth32_close | Disconnect Method | Disconnect Method |