ACCES Ethernet/Wiznet System Documentation

Client API

To install the client, simply copy AIOETHW.dll next to the program that will use it, or to the 32-bit system directory.

The general sequence to use it is:

AEW_Connect() to open a connection.
Optionally, AEW_SetTimeout() to set the connection's timeout.
Repeated calls to AEW_DIO_WriteAll() to actually write data.
Optionally, AEW_DIO_ReadAll() to read back the written data.
Optionally, AEW_GetStatus() to check the device's status.
AEW_Disconnect() to close the connection when done.

If the connection fails during operation, a new connection can be swapped in, like this:

AEW_Disconnect() to close the old connection.
AEW_Connect() to open a new connection.
Optionally, AEW_SetTimeout() to set the connection's timeout.
Resume with the calls to AEW_DIO_WriteAll().

AEW_Connect()


function AEW_Connect(Host: PChar; Index: LongInt): LongWord; cdecl; external 'AIOETHW.dll';

__declspec(dllimport) unsigned long AEW_Connect(char *Host, signed long Index);

AEW_Connect() connects to the specified host device. It returns a client reference (like a handle) that represents the connection, or zero on a failure.

Host can be an IP address in dotted decimal string form (like "192.168.1.174"), a DNS name (like "do.overthere.com"), or a name in the HOSTS file (like "localhost").

Index is normally 0. This connects to port 51936; other values are reserved for future expansion.

The returned client reference is opaque — just a 4-byte value that you pass to the other AEW_* APIs when dealing with that connection. While this is similar to a handle, it doesn't work with any handle-specific APIs, like GetHandleInformation() or CloseHandle(). On a failure, the returned reference will be zero, and the associated Windows error code can be retrieved via GetLastError(). Error codes include:

ERROR_NOACCESS if an error(usually an access violation) occurred while trying to access the buffer pointed to by Host.
ERROR_NO_NETWORK if no socket could be created at all.
ERROR_NO_NET_OR_BAD_PATH if the connection could not be established.

The server does allow more than one client to connect to a single device. This feature is intended for recovery from network problems, but does allow (for example) two programs to connect, one that writes data and one that checks status.

AEW_Disconnect()


function AEW_Disconnect(uClientRef: LongWord): LongWord; cdecl; external 'AIOETHW.dll';

__declspec(dllimport) unsigned long AEW_Disconnect(unsigned long uClientRef);

AEW_Disconnect() disconnects a client reference, closing the connection and cleaning up any memory used. After being passed to AEW_Disconnect(), the client reference is invalid.

AEW_SetTimeout()


function AEW_SetTimeout(uClientRef: LongWord; TimeoutMS: LongInt): LongWord; cdecl; external 'AIOETHW.dll';

__declspec(dllimport) unsigned long AEW_SetTimeout(unsigned long uClientRef, signed long TimeoutMS);

AEW_SetTimeout() sets the inter-receive timeout for reply packets. This is a client setting, and thus setting it doesn't involve network traffic.

TimeoutMS is the new timeout, in milliseconds. The default for a new connection is 2000.

The return value is ERROR_SUCCESS (equal to zero) on success, or another Windows error code on failure. Error codes include:

ERROR_INVALID_HANDLE if the client reference is invalid.
ERROR_NOT_CONNECTED if the connection has closed, usually a networking issue. (To reconnect, close this client ref and call AED_Connect() to get a new one.)
ERROR_BAD_LENGTH if TimeoutMS is zero or negative.

AEW_ChangeNetworking()


function AEW_ChangeNetworking(uClientRef: LongWord; NewIP, NewSubnet, NewGateway: PChar): LongWord; cdecl; external 'AIOETHW.dll';

__declspec(dllimport) unsigned long AEW_ChangeNetworking(unsigned long uClientRef, char *NewIP, char *NewSubnet, char *NewGateway);

AEW_ChangeNetworking() changes the device's IP address, subnet mask, and gateway IP address. This change takes effect immediately; the device will close its end of the connection, so on success you should disconnect with AEW_Disconnect(). After a short time you can connect to the new IP with AEW_Connect().

NewIP is the new IP address in dotted decimal string form (like "192.168.1.174").

NewSubnet is the new subnet mask in dotted decimal string form (like "255.255.0.0").

NewGateway is the new gateway IP address in dotted decimal string form (like "192.168.1.1").

The return value is ERROR_SUCCESS (equal to zero) on success, or another Windows error code on failure. Error codes include:

ERROR_INVALID_HANDLE if the client reference is invalid.
ERROR_NOT_CONNECTED if the connection has closed, usually a networking issue. (To reconnect, close this client ref and call AED_Connect() to get a new one.)
ERROR_NOACCESS if an error(usually an access violation) occurred while trying to access the string pointed to by NewIP, NewSubnet, or NewGateway.
ERROR_INVALID_ADDRESS if one of the strings was not a valid address or address mask.
ERROR_TIMEOUT if there was a timeout waiting for the reply.
ERROR_READ_FAULT or ERROR_INVALID_DATA if the reply packet was not interpretable. This may mean the network stream is corrupt; if it persists, disconnect this client ref and call AEW_Connect() to get a new one.
ERROR_BAD_NET_RESP if there was an error on the other end; use GetLastError() to tell what the error was. This may mean the device needs to be restarted.

AEW_ChangeDeviceIP()


function AEW_ChangeDeviceIP(uClientRef: LongWord; NewIP: PChar): LongWord; cdecl; external 'AIOETHW.dll';

__declspec(dllimport) unsigned long AEW_ChangeDeviceIP(unsigned long uClientRef, char *NewIP);

AEW_ChangeDeviceIP() is similar to AEW_ChangeNetworking(), except it only changes the IP address.

AEW_ChangeSubnet()


function AEW_ChangeSubnet(uClientRef: LongWord; NewSubnet: PChar): LongWord; cdecl; external 'AIOETHW.dll';

__declspec(dllimport) unsigned long AEW_ChangeSubnet(unsigned long uClientRef, char *NewSubnet);

AEW_ChangeSubnet() is similar to AEW_ChangeNetworking(), except it only changes the subnet mask.

AEW_ChangeGateway()


function AEW_ChangeGateway(uClientRef: LongWord; NewGateway: PChar): LongWord; cdecl; external 'AIOETHW.dll';

__declspec(dllimport) unsigned long AEW_ChangeGateway(unsigned long uClientRef, char *NewGateway);

AEW_ChangeGateway() is similar to AEW_ChangeNetworking(), except it only changes the gateway IP address.

AEW_GetStatus()


function AEW_GetStatus(uClientRef: LongWord; pStatusBytes: PLongInt; pStatus: PByte): LongWord; cdecl; external 'AIOETHW.dll';

__declspec(dllimport) unsigned long AEW_GetStatus(unsigned long uClientRef, signed long *pStatusBytes, unsigned char *pStatus);

AEW_GetStatus() reads the device's status block.

pStatusBytes is a pointer to a variable that holds the size of the buffer to read into, in bytes. On return, this variable will be set to the number of status bytes read.

pStatus is a pointer to the buffer to read into.

The return value is ERROR_SUCCESS (equal to zero) on success, or another Windows error code on failure. Error codes include:

ERROR_INVALID_HANDLE if the client reference is invalid.
ERROR_NOT_CONNECTED if the connection has closed, usually a networking issue. (To reconnect, close this client ref and call AED_Connect() to get a new one.)
ERROR_BAD_LENGTH if the variable pointed to by pStatusBytes is zero or negative.
ERROR_NOACCESS if an error(usually an access violation) occurred while trying to access the buffer pointed to by pStatus.
ERROR_TIMEOUT if there was a timeout waiting for the reply.
ERROR_READ_FAULT or ERROR_INVALID_DATA if the reply packet was not interpretable. This may mean the network stream is corrupt; if it persists, disconnect this client ref and call AEW_Connect() to get a new one.
ERROR_BAD_NET_RESP if there was an error on the other end; use GetLastError() to tell what the error was. This may mean the device needs to be restarted.

AEW_DIO_WriteAll()


function AEW_DIO_WriteAll(uClientRef: LongWord; pDataBytes: PLongInt; pData: PByte): LongWord; cdecl; external 'AIOETHW.dll';

__declspec(dllimport) unsigned long AEW_DIO_WriteAll(unsigned long uClientRef, signed long *pDataBytes, unsigned char *pData);

AEW_DIO_WriteAll() writes to all the DIO.

pDataBytes is a pointer to a variable that holds the size of the buffer to write from, in bytes. On return, this variable will be set to the amount of data written. For the ETH-DO-8, the variable should always be 1.

pData is a pointer to the buffer to write from.

The return value is ERROR_SUCCESS (equal to zero) on success, or another Windows error code on failure. Error codes include:

ERROR_INVALID_HANDLE if the client reference is invalid.
ERROR_NOT_CONNECTED if the connection has closed, usually a networking issue. (To reconnect, close this client ref and call AED_Connect() to get a new one.)
ERROR_BAD_LENGTH if the variable pointed to by pStatusBytes is zero or negative.
ERROR_NOACCESS if an error(usually an access violation) occurred while trying to access the buffer pointed to by pData.
ERROR_TIMEOUT if there was a timeout waiting for the reply.
ERROR_READ_FAULT or ERROR_INVALID_DATA if the reply packet was not interpretable. This may mean the network stream is corrupt; if it persists, disconnect this client ref and call AEW_Connect() to get a new one.
ERROR_BAD_NET_RESP if there was an error on the other end; use GetLastError() to tell what the error was. This may mean the device needs to be restarted.

AEW_DIO_ReadAll()


function AEW_DIO_ReadAll(uClientRef: LongWord; pDataBytes: PLongInt; pData: PByte): LongWord; cdecl; external 'AIOETHW.dll';

__declspec(dllimport) unsigned long AEW_DIO_ReadAll(unsigned long uClientRef, signed long *pDataBytes, unsigned char *pData);

AEW_DIO_ReadAll() reads from all the DIO.

pDataBytes is a pointer to a variable that holds the size of the buffer to read to, in bytes. On return, this variable will be set to the amount of data read. For the ETH-DO-8, the variable should always be 1.

pData is a pointer to the buffer to read to.

The return value is ERROR_SUCCESS (equal to zero) on success, or another Windows error code on failure. Error codes include:

ERROR_INVALID_HANDLE if the client reference is invalid.
ERROR_NOT_CONNECTED if the connection has closed, usually a networking issue. (To reconnect, close this client ref and call AED_Connect() to get a new one.)
ERROR_BAD_LENGTH if the variable pointed to by pStatusBytes is zero or negative.
ERROR_NOACCESS if an error(usually an access violation) occurred while trying to access the buffer pointed to by pData.
ERROR_TIMEOUT if there was a timeout waiting for the reply.
ERROR_READ_FAULT or ERROR_INVALID_DATA if the reply packet was not interpretable. This may mean the network stream is corrupt; if it persists, disconnect this client ref and call AEW_Connect() to get a new one.
ERROR_BAD_NET_RESP if there was an error on the other end; use GetLastError() to tell what the error was. This may mean the device needs to be restarted.

Packet Structure

A packet is a byte-lengthed string; the first byte is the length(in bytes) of the body. A packet's body consists of a 4-byte ASCII type and zero or more bytes of payload.

Defined packet types are as follows:

Type	Direction	Meaning	Payload
ChNW	M>S	Change network settings.	IP address, subnet mask, and gateway IP address, each in 4-byte big-endian format. For example, `C0 A8 01 AE FF FF FF 00 C0 A8 01 01` for 192.168.1.174, 255.255.255.0, and 192.168.1.1. Device should reply with W_OK or _Err.
ChIP	M>S	Change IP address.	4-byte big-endian IP address. For example, `C0 A8 01 AE` for 192.168.1.174. Device should reply with W_OK or _Err.
ChSN	M>S	Change subnet mask.	4-byte big-endian subnet mask. For example, `FF FF FF 00` for 255.255.255.0. Device should reply with W_OK or _Err.
ChGW	M>S	Change gateway IP address.	4-byte big-endian gateway IP address. For example, `C0 A8 01 01` for 192.168.1.1. Device should reply with W_OK or _Err.
RSta	M>S	Read status.	No payload defined at this time. Device should reply with R_OK or _Err.
RADI	M>S	Read "all" DIO data.	No payload defined at this time. Device should reply with R_OK or _Err.
RPDI	Reserved for reading partial DIO data.
WADO	M>S	Write "all" DIO data.	1-byte length of DIO data, then DIO data. For example, `01 A5` to set bits 0, 2, 5, and 7 high and the rest low on the first byte of DIO. Device should reply with W_OK or _Err.
WPDO	Reserved for writing partial DIO data.
W_OK	S>M	Write succeeded.	1-byte length of written data. For example, `01` to indicate success of a 1-byte write.
R_OK	S>M	Read succeeded.	1-byte length of read data, then read data. For example, `03 42 49 4F` to read 42h, 49h, and 4Fh.
_Err	S>M	Transaction failed.	4-byte little-endian Windows error code. For example, `42 00 00 00` for ERROR_BAD_DEV_TYPE, indicating read from a write-only device or vice versa.