TwinCat 的API函数

AdsGetDllVersion

Returns the version number, revision number and build number of the ADS-DLL.

LONG AdsGetDllVersion( void );

Parameter

-

Return value

The return value, which is of type long, contains in coded form these three items related to the ADS-DLL.

AdsPortOpen

Establishes a connection (communication port) to the TwinCAT message router.

LONG AdsPortOpen( void );

Parameter

-

Return value

A port number that has been assigned to the program by the ADS router is returned.

AdsPortClose

The connection (communication port) to the TwinCAT message router is closed.

LONG AdsPortClose( void );

Parameter

-

Return value

Returns the function's error status.

AdsGetLocalAddress

Returns the local NetId and port number.

LONG AdsGetLocalAddress( PAmsAddr pAddr );

Parameter

pAddr

[out] Pointer to the structure of type AmsAddr.

Return value

Returns the function's error status.

AdsSyncWriteReq

Writes data synchronously to an ADS device.

LONG AdsSyncWriteReq( PAmsAddr pAddr, ULONG nIndexGroup, ULONG nIndexOffset, ULONG nLength, PVOID pData );

Parameter

pAddr

[in] Structure with NetId and port number of the ADS server. nIndexGroup [in] Index Group. nIndexOffset [in] Index Offset. nLength

[in] Length of the data, in bytes, written to the ADS server. pData

[in] Pointer to the data written to the ADS server.

Return value

Returns the function's error status.

AdsSyncReadReq

Reads data synchronously from an ADS server.

LONG AdsSyncReadReq( PAmsAddr pAddr, ULONG nIndexGroup, ULONG nIndexOffset, ULONG nLength, PVOID pData );

Parameter

pAddr

[in] Structure with NetId and port number of the ADS server. nIndexGroup [in] Index Group. nIndexOffset [in] Index Offset. nLength

[in] Length of the data in bytes. pData

[out] Pointer to a data buffer that will receive the data.

Return value

Returns the function's error status.

AdsSyncReadReqEx

Reads data synchronously from an ADS server.

LONG AdsSyncReadReq( PAmsAddr pAddr, ULONG nIndexGroup, ULONG nIndexOffset, ULONG nLength, PVOID pData, ULONG* pcbReturn );

Parameter

pAddr

[in] Structure with NetId and port number of the ADS server. nIndexGroup [in] Index Group. nIndexOffset [in] Index Offset. nLength

[in] Length of the data in bytes. pData

[out] Pointer to a data buffer that will receive the data. pcbReturn

[out] Pointer to a variable. This variable returns the number of succesfully read data bytes.

Return value

Returns the function's error status.

AdsSyncReadWriteReq

Writes data synchronously into an ADS server and receives data back from the ADS device.

LONG AdsSyncReadWriteReq( PAmsAddr pAddr, ULONG nIndexGroup, ULONG nIndexOffset, ULONG nReadLength, PVOID pReadData, ULONG nWriteLength, PVOID pWriteData );

Parameter

pAddr

[in] Structure with NetId and port number of the ADS server. nIndexGroup [in] Index Group. nIndexOffset [in] Index Offset. nReadLength

[in] Length of the data, in bytes, returned by the ADS device. pReadData

[out] Buffer with data returned by the ADS device. nWriteLength

[in] Length of the data, in bytes, written to the ADS device. pWriteData

[out] Buffer with data written to the ADS device.

Return value

Returns the function's error status.

AdsSyncReadWriteReqEx

Writes data synchronously into an ADS server and receives data back from the ADS device.

LONG AdsSyncReadWriteReq( PAmsAddr pAddr, ULONG nIndexGroup, ULONG nIndexOffset, ULONG nReadLength, PVOID pReadData, ULONG nWriteLength, PVOID pWriteData, ULONG* pcbReturn );

Parameter

pAddr

[in] Structure with NetId and port number of the ADS server. nIndexGroup [in] Index Group. nIndexOffset [in] Index Offset. nReadLength

[in] Length of the data, in bytes, returned by the ADS device. pReadData

[out] Buffer with data returned by the ADS device. nWriteLength

[in] Length of the data, in bytes, written to the ADS device. pWriteData

[out] Buffer with data written to the ADS device. pcbReturn

[out] Pointer to a variable. This variable returns the number of succesfully read data bytes.

AdsSyncReadDeviceInfoReq

Reads the identification and version number of an ADS server.

LONG AdsSyncReadDeviceInfoReq( PAmsAddr pAddr, PCHAR pDevName,

PAdsVersion pVersion );

Parameter

pAddr

[in] Structure with NetId and port number of the ADS server. pDevName

[out] Pointer to a character string that will receive the name of the ADS device. pVersion

[out] Address of a variable of type AdsVersion, which will receive the version number, revision number and the build number.

Return value

Returns the function's error status.

AdsSyncWriteControlReq

Changes the ADS status and the device status of an ADS server.

LONG AdsSyncWriteControlReq( PAmsAddr pAddr, USHORT nAdsState, USHORT nDeviceState, ULONG nLength, PVOID pData );

Parameter

pAddr

[in] Structure with NetId and port number of the ADS server. nAdsState

[in] New ADS status. nDeviceState

[in] New device status. nLength

[in] Length of the data in bytes. pData

[in] Pointer to data sent additionally to the ADS device.

Return value

Returns the function's error status.

Comments

In addition to changing the ADS status and the device status, it is also possible to send data to the ADS server in order to transfer further information. In the current ADS devices (PLC, NC, ...) this data has no further effect. Any ADS device can inform another ADS device of its current state. A distinction is drawn here between the status of the device itself (DeviceState) and the status of the ADS interface of the ADS device (AdsState). The states that the ADS interface can adopt are laid down in the ADS specification.

AdsSyncReadStateReq

Reads the ADS status and the device status from an ADS server.

LONG AdsSyncReadStateReq( PAmsAddr pAddr, USHORT *pAdsState, PUSHORT pDeviceState );

Parameter

pAddr

[in] Structure with NetId and port number of the ADS server. pAdsState

[out] Address of a variable that will receive the ADS status (see data type ADSSTATE). pDeviceState

[out] Address of a variable that will receive the device status.

Return value

Returns the function's error status.

Remarks

Any ADS device can inform another ADS device of its current state. A distinction is drawn here between the status of the device itself (DeviceState) and the status of the ADS interface of the ADS device (AdsState). The states that the ADS interface can adopt are laid down in the ADS specification.

AdsSyncAddDeviceNotificationReq

A notification is defined within an ADS server (e.g. PLC). When a certain event occurs a function (the callback function) is invoked in the ADS client (C program).

LONG AdsSyncAddDeviceNotificationReq( PAmsAddr pAddr, ULONG nIndexGroup, ULONG nIndexOffset, PAdsNotificationAttrib pNoteAttrib, PAdsNotificationFuncEx pNoteFunc, ULONG hUser, PULONG pNotification );

Parameter

pAddr

[in] Structure with NetId and port number of the ADS server. nIndexGroup [in] IndexGroup. nIndexOffset [in] IndexOffset. pNoteAttrib

[in] Pointer to the structure that contains further information. pNoteFunc

[in] Name of the callback function. hUser

[in] 32-bit value that is passed to the callback function. pNotification

[out] Address of the variable that will receive the handle of the notification.

Return value

Returns the function's error status.

Limitation:

Per ADS-Port a limitted number of 550 notifications are available.

AdsSyncDelDeviceNotificationReq

A notification defined previously is deleted from an ADS server.

LONG AdsSyncDelDeviceNotificationReq( PAmsAddr pAddr, ULONG hNotification );

Parameter

pAddr

[in] Structure with NetId and port number of the ADS server. hNotification

[out] Address of the variable that contains the handle of the notification.

Return value

Returns the function's error status.

AdsSyncSetTimeout

Alters the timeout for the ADS functions. The standard value is 5000 ms.

LONG AdsSyncSetTimeout( LONG nMs, );

Parameter

nMs

[in] Timeout in ms.

Return value

Returns the function's error status.

AdsAmsRegisterRouterNotification

The AdsAmsRegisterNotificationReq() function can be used to detect a change in the status of the TwinCAT router. The given callback function is invoked each time the status changes. Monitoring of the router's status is ended once more by the AdsAmsUnRegisterNotification() function.

LONG AdsAmsRegisterRouterNotification(

PAmsRouterNotificationFuncEx pNoteFunc );

Parameter

pNoteFunc

[in] Name of the callback function

Return value

Returns the function's error status. Hints:

? Implemented from TcAdsDLL File Version: 2.8.0.21 ( delivered with TwinCAT 2.9 Build > 941). ? A connection to the TwinCAT-Router can be done, if TwinCAT has been installed on the local

PC. The function delivers an error on a system without TwinCAT.

AdsAmsUnRegisterRouterNotification

Monitoring the router's status is ended by the AdsAmsUnRegisterNotification() function. See also AdsAmsRegisterNotificationReq().

LONG AdsAmsUnRegisterRouterNotification( void );

Parameter

-

Return value

Returns the function's error status. Hints:

? Implemented from TcAdsDLL File Version: 2.8.0.21 ( delivered with TwinCAT 2.9 Build > 941). ? A connection to the TwinCAT-Router can be done, if TwinCAT has been installed on the local

PC. The function delivers an error on a system without TwinCAT.

PAmsRouterNotificationFuncEx

Type definition of the callback function required by the AdsAmsRegisterRouterNotification function.

typedef void ( __stdcall *PAmsRouterNotificationFuncEx)( long nEvent );

PAdsNotificationFuncEx

Type definition of the callback function required by the AdsSyncAddDeviceNotificationReq function.

typedef void (__stdcall *PAdsNotificationFuncEx)(AmsAddr* pAddr, AdsNotificationHeader* pNotification, unsigned long hUser );

MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM

AdsPortOpenEx

Establishes a connection (communication port) to the TwinCAT message router. Unlike with

AdsPortOpen, a new ADS port is opened each time. The extended Ads functions have to be used for communicating with this port. The port number returned by AdsPortOpenEx is transferred as parameter to these functions. If no TwinCAT MessageRouter is present, the AdsPortOpenEx function will fail.

LONG AdsPortOpenEx( void );

Parameters

-

Return value

Port number of the opened Ads port. A return value of 0 means the call has failed.

AdsPortCloseEx

The connection (communication port) to the TwinCAT message router is closed. The port to be closed must previously have been opened via an AdsPortOpenEx call.

LONG AdsPortCloseEx( long nPort );

Parameters

port

[in] port number of an Ads port that had previously been opened with AdsPortOpenEx.

Return value

Returns the function's error status.

AdsGetLocalAddressEx

Returns the local NetId and port number.

LONG AdsGetLocalAddressEx( long port PAmsAddr pAddr );

Parameters

port

[in] port number of an Ads port that had previously been opened with AdsPortOpenEx or AdsPortOpen. pAddr

[out] Pointer to the structure of type AmsAddr.

Return value

Returns the function's error status.

AdsSyncWriteReqEx

Writes data synchronously to an ADS device.

LONG AdsSyncWriteReqEx( LONG port, PAmsAddr pAddr, ULONG nIndexGroup, ULONG nIndexOffset, ULONG nLength, PVOID pData );

Parameters

port

[in] port number of an Ads port that had previously been opened with AdsPortOpenEx or AdsPortOpen. pAddr

[in] Structure with NetId and port number of the ADS server. nIndexGroup [in] Index Group. nIndexOffset [in] Index Offset.

nLength

[in] Length of the data, in bytes, written to the ADS server. pData

[in] Pointer to the data written to the ADS server.

Return value

Returns the function's error status.

AdsSyncReadReqEx2

Reads data synchronously from an ADS server.

LONG AdsSyncReadReqEx2( LONG port, PAmsAddr pAddr, ULONG nIndexGroup, ULONG nIndexOffset, ULONG nLength, PVOID pData, ULONG* pcbReturn );

Parameters

port

[in] port number of an Ads port that had previously been opened with AdsPortOpenEx or AdsPortOpen. pAddr

[in] Structure with NetId and port number of the ADS server. nIndexGroup [in] Index Group. nIndexOffset [in] Index Offset. nLength

[in] Length of the data in bytes. pData

[out] Pointer to a data buffer that will receive the data. pcbReturn

[out] pointer to a variable. If successful, this variable will return the number of actually read data bytes.

AdsSyncReadWriteReqEx2

Writes data synchronously into an ADS server and receives data back from the ADS device.

LONG AdsSyncReadWriteReqEx2( LONG port, PAmsAddr pAddr, ULONG nIndexGroup, ULONG nIndexOffset, ULONG nReadLength, PVOID pReadData, ULONG nWriteLength, PVOID pWriteData, ULONG* pcbReturn );

Parameters

port

[in] port number of an Ads port that had previously been opened with AdsPortOpenEx or AdsPortOpen. pAddr

[in] Structure with NetId and port number of the ADS server. nIndexGroup [in] Index Group. nIndexOffset [in] Index Offset. nReadLength

[in] Length of the data, in bytes, returned by the ADS device. pReadData

[out] Buffer with data returned by the ADS device. nWriteLength

[in] Length of the data, in bytes, written to the ADS device. pWriteData

[out] Buffer with data written to the ADS device. pcbReturn

[out] pointer to a variable. If successful, this variable will return the number of actually read data bytes.

AdsSyncReadDeviceInfoReqEx

Reads the identification and version number of an ADS server.

本文来源：https://www.bwwdw.com/article/876d.html