TwinCat 的API函数.docx

TwinCat 的API函数.docx

《TwinCat 的API函数.docx》由会员分享，可在线阅读，更多相关《TwinCat 的API函数.docx（24页珍藏版）》请在冰豆网上搜索。

TwinCat的API函数

AdsGetDllVersion

Returnstheversionnumber,revisionnumberandbuildnumberoftheADS-DLL.

LONGAdsGetDllVersion（

void

）;

Parameter

-

Returnvalue

Thereturnvalue,whichisoftypelong,containsincodedformthesethreeitemsrelatedtotheADS-DLL.

AdsPortOpen

Establishesaconnection（communicationport）totheTwinCATmessagerouter.

LONGAdsPortOpen（

void

）;

Parameter

-

Returnvalue

AportnumberthathasbeenassignedtotheprogrambytheADSrouterisreturned.

AdsPortClose

Theconnection（communicationport）totheTwinCATmessagerouterisclosed.

LONGAdsPortClose（

void

）;

Parameter

-

Returnvalue

Returnsthefunction'serrorstatus.

AdsGetLocalAddress

ReturnsthelocalNetIdandportnumber.

LONGAdsGetLocalAddress（

PAmsAddrpAddr

）;

Parameter

pAddr

[out]PointertothestructureoftypeAmsAddr.

Returnvalue

Returnsthefunction'serrorstatus.

AdsSyncWriteReq

WritesdatasynchronouslytoanADSdevice.

LONGAdsSyncWriteReq（

PAmsAddrpAddr,

ULONGnIndexGroup,

ULONGnIndexOffset,

ULONGnLength,

PVOIDpData

）;

Parameter

pAddr

[in]StructurewithNetIdandportnumberoftheADSserver.

nIndexGroup

[in]IndexGroup.

nIndexOffset

[in]IndexOffset.

nLength

[in]Lengthofthedata,inbytes,writtentotheADSserver.

pData

[in]PointertothedatawrittentotheADSserver.

Returnvalue

Returnsthefunction'serrorstatus.

AdsSyncReadReq

ReadsdatasynchronouslyfromanADSserver.

LONGAdsSyncReadReq（

PAmsAddrpAddr,

ULONGnIndexGroup,

ULONGnIndexOffset,

ULONGnLength,

PVOIDpData

）;

Parameter

pAddr

[in]StructurewithNetIdandportnumberoftheADSserver.

nIndexGroup

[in]IndexGroup.

nIndexOffset

[in]IndexOffset.

nLength

[in]Lengthofthedatainbytes.

pData

[out]Pointertoadatabufferthatwillreceivethedata.

Returnvalue

Returnsthefunction'serrorstatus.

AdsSyncReadReqEx

ReadsdatasynchronouslyfromanADSserver.

LONGAdsSyncReadReq（

PAmsAddrpAddr,

ULONGnIndexGroup,

ULONGnIndexOffset,

ULONGnLength,

PVOIDpData,

ULONG*pcbReturn

）;

Parameter

   pAddr

   [in]StructurewithNetIdandportnumberoftheADSserver.

   nIndexGroup

   [in]IndexGroup.

   nIndexOffset

   [in]IndexOffset.

   nLength

   [in]Lengthofthedatainbytes.

   pData

   [out]Pointertoadatabufferthatwillreceivethedata.

pcbReturn

[out]Pointertoavariable.Thisvariablereturnsthenumberofsuccesfullyreaddatabytes.

Returnvalue

Returnsthefunction'serrorstatus.

AdsSyncReadWriteReq

WritesdatasynchronouslyintoanADSserverandreceivesdatabackfromtheADSdevice.

LONGAdsSyncReadWriteReq（

PAmsAddrpAddr,

ULONGnIndexGroup,

ULONGnIndexOffset,

ULONGnReadLength,

PVOIDpReadData,

ULONGnWriteLength,

PVOIDpWriteData

）;

Parameter

pAddr

[in]StructurewithNetIdandportnumberoftheADSserver.

nIndexGroup

[in]IndexGroup.

nIndexOffset

[in]IndexOffset.

nReadLength

[in]Lengthofthedata,inbytes,returnedbytheADSdevice.

pReadData

[out]BufferwithdatareturnedbytheADSdevice.

nWriteLength

[in]Lengthofthedata,inbytes,writtentotheADSdevice.

pWriteData

[out]BufferwithdatawrittentotheADSdevice.

Returnvalue

Returnsthefunction'serrorstatus.

AdsSyncReadWriteReqEx

WritesdatasynchronouslyintoanADSserverandreceivesdatabackfromtheADSdevice.

LONGAdsSyncReadWriteReq（

PAmsAddrpAddr,

ULONGnIndexGroup,

ULONGnIndexOffset,

ULONGnReadLength,

PVOIDpReadData,

ULONGnWriteLength,

PVOIDpWriteData,

ULONG*pcbReturn

）;

Parameter

   pAddr

   [in]StructurewithNetIdandportnumberoftheADSserver.

   nIndexGroup

   [in]IndexGroup.

   nIndexOffset

   [in]IndexOffset.

   nReadLength

   [in]Lengthofthedata,inbytes,returnedbytheADSdevice.

   pReadData

   [out]BufferwithdatareturnedbytheADSdevice.

   nWriteLength

   [in]Lengthofthedata,inbytes,writtentotheADSdevice.

   pWriteData

   [out]BufferwithdatawrittentotheADSdevice.

pcbReturn

[out]Pointertoavariable.Thisvariablereturnsthenumberofsuccesfullyreaddatabytes.

AdsSyncReadDeviceInfoReq

ReadstheidentificationandversionnumberofanADSserver.

LONGAdsSyncReadDeviceInfoReq（

PAmsAddrpAddr,

PCHARpDevName,

PAdsVersionpVersion

）;

Parameter

pAddr

[in]StructurewithNetIdandportnumberoftheADSserver.

pDevName

[out]PointertoacharacterstringthatwillreceivethenameoftheADSdevice.

pVersion

[out]AddressofavariableoftypeAdsVersion,whichwillreceivetheversionnumber,revisionnumberandthebuildnumber.

Returnvalue

Returnsthefunction'serrorstatus.

AdsSyncWriteControlReq

ChangestheADSstatusandthedevicestatusofanADSserver.

LONGAdsSyncWriteControlReq（

PAmsAddrpAddr,

USHORTnAdsState,

USHORTnDeviceState,

ULONGnLength,

PVOIDpData

）;

Parameter

pAddr

[in]StructurewithNetIdandportnumberoftheADSserver.

nAdsState

[in]NewADSstatus.

nDeviceState

[in]Newdevicestatus.

nLength

[in]Lengthofthedatainbytes.

pData

[in]PointertodatasentadditionallytotheADSdevice.

Returnvalue

Returnsthefunction'serrorstatus.

Comments

InadditiontochangingtheADSstatusandthedevicestatus,itisalsopossibletosenddatatotheADSserverinordertotransferfurtherinformation.InthecurrentADSdevices（PLC,NC,...）thisdatahasnofurthereffect.AnyADSdevicecaninformanotherADSdeviceofitscurrentstate.Adistinctionisdrawnherebetweenthestatusofthedeviceitself（DeviceState）andthestatusoftheADSinterfaceoftheADSdevice（AdsState）.ThestatesthattheADSinterfacecanadoptarelaiddownintheADSspecification.

AdsSyncReadStateReq

ReadstheADSstatusandthedevicestatusfromanADSserver.

LONGAdsSyncReadStateReq（

PAmsAddrpAddr,

USHORT*pAdsState,

PUSHORTpDeviceState

）;

Parameter

pAddr

[in]StructurewithNetIdandportnumberoftheADSserver.

pAdsState

[out]AddressofavariablethatwillreceivetheADSstatus（seedatatypeADSSTATE）.

pDeviceState

[out]Addressofavariablethatwillreceivethedevicestatus.

Returnvalue

Returnsthefunction'serrorstatus.

Remarks

AnyADSdevicecaninformanotherADSdeviceofitscurrentstate.Adistinctionisdrawnherebetweenthestatusofthedeviceitself（DeviceState）andthestatusoftheADSinterfaceoftheADSdevice（AdsState）.ThestatesthattheADSinterfacecanadoptarelaiddownintheADSspecification.

AdsSyncAddDeviceNotificationReq

AnotificationisdefinedwithinanADSserver（e.g.PLC）.Whenacertaineventoccursafunction（thecallbackfunction）isinvokedintheADSclient（Cprogram）.

LONGAdsSyncAddDeviceNotificationReq（

PAmsAddrpAddr,

ULONGnIndexGroup,

ULONGnIndexOffset,

PAdsNotificationAttribpNoteAttrib,

PAdsNotificationFuncExpNoteFunc,

ULONGhUser,

PULONGpNotification

）;

Parameter

pAddr

[in]StructurewithNetIdandportnumberoftheADSserver.

nIndexGroup

[in]IndexGroup.

nIndexOffset

[in]IndexOffset.

pNoteAttrib

[in]Pointertothestructurethatcontainsfurtherinformation.

pNoteFunc

[in]Nameofthecallbackfunction.

hUser

[in]32-bitvaluethatispassedtothecallbackfunction.

pNotification

[out]Addressofthevariablethatwillreceivethehandleofthenotification.

Returnvalue

Returnsthefunction'serrorstatus.

Limitation:

PerADS-Portalimittednumberof550notificationsareavailable.

AdsSyncDelDeviceNotificationReq

AnotificationdefinedpreviouslyisdeletedfromanADSserver.

LONGAdsSyncDelDeviceNotificationReq（

PAmsAddrpAddr,

ULONGhNotification

）;

Parameter

pAddr

[in]StructurewithNetIdandportnumberoftheADSserver.

hNotification

[out]Addressofthevariablethatcontainsthehandleofthenotification.

Returnvalue

Returnsthefunction'serrorstatus.

AdsSyncSetTimeout

AltersthetimeoutfortheADSfunctions.Thestandardvalueis5000ms.

LONGAdsSyncSetTimeout（

LONGnMs,

）;

Parameter

nMs

[in]Timeoutinms.

Returnvalue

Returnsthefunction'serrorstatus.

AdsAmsRegisterRouterNotification

TheAdsAmsRegisterNotificationReq（）functioncanbeusedtodetectachangeinthestatusoftheTwinCATrouter.Thegivencallbackfunctionisinvokedeachtimethestatuschanges.Monitoringoftherouter'sstatusisendedoncemorebytheAdsAmsUnRegisterNotification（）function.

LONGAdsAmsRegisterRouterNotification（

PAmsRouterNotificationFuncExpNoteFunc）;

Parameter

pNoteFunc

[in]Nameofthecallbackfunction

Returnvalue

Returnsthefunction'serrorstatus.

Hints:

∙ImplementedfromTcAdsDLLFileVersion:

2.8.0.21（deliveredwithTwinCAT2.9Build>941）.

∙AconnectiontotheTwinCAT-Routercanbedone,ifTwinCAThasbeeninstalledonthelocalPC.ThefunctiondeliversanerroronasystemwithoutTwinCAT.

AdsAmsUnRegisterRouterNotification

Monitoringtherouter'sstatusisendedbytheAdsAmsUnRegisterNotification（）function.SeealsoAdsAmsRegisterNotificationReq（）.

LONGAdsAmsUnRegisterRouterNotification（void）;

Parameter

-

Returnvalue

Returnsthefunction'serrorstatus.

Hints:

∙ImplementedfromTcAdsDLLFileVersion:

2.8.0.21（deliveredwithTwinCAT2.9Build>941）.

∙AconnectiontotheTwinCAT-Routercanbedone,ifTwinCAThasbeeninstalledonthelocalPC.ThefunctiondeliversanerroronasystemwithoutTwinCAT.

PAmsRouterNotificationFuncEx

TypedefinitionofthecallbackfunctionrequiredbytheAdsAmsRegisterRouterNotificationfunction.

typedefvoid（__stdcall*PAmsRouterNotificationFuncEx）（longnEvent）;

PAdsNotificationFuncEx

TypedefinitionofthecallbackfunctionrequiredbytheAdsSyncAddDeviceNotificationReqfuncti