Hinweise zur Dokumentation

Diese Beschreibung wendet sich ausschließlich an ausgebildetes Fachpersonal der Steuerungs- und Automatisierungstechnik, das mit den geltenden nationalen Normen vertraut ist.
Zur Installation und Inbetriebnahme der Komponenten ist die Beachtung der Dokumentation und der nachfolgenden Hinweise und Erklärungen unbedingt notwendig.
Das Fachpersonal ist verpflichtet, für jede Installation und Inbetriebnahme die zu dem Zeitpunkt veröffentlichte Dokumentation zu verwenden.

Das Fachpersonal hat sicherzustellen, dass die Anwendung bzw. der Einsatz der beschriebenen Produkte alle Sicherheitsanforderungen, einschließlich sämtlicher anwendbaren Gesetze, Vorschriften, Bestimmungen und Normen erfüllt.

Disclaimer

Diese Dokumentation wurde sorgfältig erstellt. Die beschriebenen Produkte werden jedoch ständig weiter entwickelt.
Wir behalten uns das Recht vor, die Dokumentation jederzeit und ohne Ankündigung zu überarbeiten und zu ändern.
Aus den Angaben, Abbildungen und Beschreibungen in dieser Dokumentation können keine Ansprüche auf Änderung bereits gelieferter Produkte geltend gemacht werden.

Marken

Beckhoff®, TwinCAT®, EtherCAT®, EtherCAT G®, EtherCAT G10®, EtherCAT P®, Safety over EtherCAT®, TwinSAFE®, XFC®, XTS® und XPlanar® sind eingetragene und lizenzierte Marken der Beckhoff Automation GmbH.
Die Verwendung anderer in dieser Dokumentation enthaltenen Marken oder Kennzeichen durch Dritte kann zu einer Verletzung von Rechten der Inhaber der entsprechenden Bezeichnungen führen.

Patente

Die EtherCAT Technologie ist patentrechtlich geschützt, insbesondere durch folgende Anmeldungen und Patente:
EP1590927, EP1789857, EP1456722, EP2137893, DE102015105702
mit den entsprechenden Anmeldungen und Eintragungen in verschiedenen anderen Ländern.

EtherCAT® ist eine eingetragene Marke und patentierte Technologie lizenziert durch die Beckhoff Automation GmbH, Deutschland.

Copyright

© Beckhoff Automation GmbH & Co. KG, Deutschland.
Weitergabe sowie Vervielfältigung dieses Dokuments, Verwertung und Mitteilung seines Inhalts sind verboten, soweit nicht ausdrücklich gestattet.
Zuwiderhandlungen verpflichten zu Schadenersatz. Alle Rechte für den Fall der Patent-, Gebrauchsmuster- oder Geschmacksmustereintragung vorbehalten.


Overview

TwinCAT TcAdsDll: Einleitung

Einleitung

Die TcAdsDll stellt Funktionen zur Kommunikation mit anderen ADS Geräten zur Verfügung.

  • Kommunikation zu lokalen TwinCAT Systemen oder Remote TwinCAT Systemen über den TwinCAT Message Router.
  • Kommunikation zu Remote TwinCAT Systemen über TCP/IP für Win32 Systeme.

Die TCAdsDll stellt die TwinCAT ADS Client Funktionen zur Verfügung. Diese Funktionen werden für 2 unterschiedliche Wege angeboten:

  • Über C API.
  • Über COM Interfaces

Es wird empfohlen die Bibliothek mit der kostenlosen TwinCAT CP Version zu verwenden.


API Übersicht

TwinCAT TcAdsDLL: API Übersicht

Übersicht

Die TcAdsDll stellt Funktionen zur Verfügung, um mit anderen ADS-Geräten über den TwinCAT-Router mit dem C API Interface zu kommunizieren. Weiter Informationen zu ADS finden Sie unter TwinCAT ADS.

Die meisten in dieser Anleitung gezeigten Beispiele sind in Visual C++ Service Pack 3 realisiert. Da keines der Beispiele sehr komplex ist, sind tiefgreifende Kenntnisse in C/C++ nicht erforderlich.


ADS Return Codes

Error codes: 0x000..., 0x500..., 0x700..., 0x1000..., 0x274C...

Global Error Codes

Hex | Dec | Description | Possible Causes | Solution
0x0 | 0 | no error |  |
0x1 | 1 | Internal error |  |
0x2 | 2 | No Rtime |  |
0x3 | 3 | Allocation locked memory error |  |
0x4 | 4 | Insert mailbox error | No ADS mailbox was available to process this message. | Reduce the number of ADS calls (e.g ADS-Sum commands or Max Delay Parameter)
0x5 | 5 | Wrong receive HMSG |  |
0x6 | 6 | target port not found | ADS Server not started |
0x7 | 7 | target machine not found | Missing ADS routes |
0x8 | 8 | Unknown command ID |  |
0x9 | 9 | Bad task ID |  |
0xA | 10 | No IO |  |
0xB | 11 | Unknown ADS command |  |
0xC | 12 | Win 32 error |  |
0xD | 13 | Port not connected |  |
0xE | 14 | Invalid ADS length |  |
0xF | 15 | Invalid AMS Net ID |  |
0x10 | 16 | Low Installation level |  |
0x11 | 17 | No debug available |  |
0x12 | 18 | Port disabled |  |
0x13 | 19 | Port already connected |  |
0x14 | 20 | ADS Sync Win32 error |  |
0x15 | 21 | ADS Sync Timeout |  |
0x16 | 22 | ADS Sync AMS error |  |
0x17 | 23 | ADS Sync no index map |  |
0x18 | 24 | Invalid ADS port |  |
0x19 | 25 | No memory |  |
0x1A | 26 | TCP send error |  |
0x1B | 27 | Host unreachable |  |
0x1C | 28 | Invalid AMS fragment |  |

Router Error Codes

Hex | Dec | Description | Possible Causes | Solution
0x500 | 1280 | ROUTERERR_NOLOCKEDMEMORY | No locked memory can be allocated |
0x501 | 1281 | ROUTERERR_RESIZEMEMORY | The size of the router memory could not be changed |
0x502 | 1282 | ROUTERERR_MAILBOXFULL | The mailbox has reached the maximum number of possible messages. The current sent message was rejected | Check the connection between the communication partners
0x503 | 1283 | ROUTERERR_DEBUGBOXFULL | The mailbox has reached the maximum number of possible messages. The sent message will not be displayed in the debug monitor | Check the connection to the debug monitor
0x504 | 1284 | ROUTERERR_UNKNOWNPORTTYPE | The port type is unknown |
0x505 | 1285 | ROUTERERR_NOTINITIALIZED | Router is not initialised |
0x506 | 1286 | ROUTERERR_PORTALREADYINUSE | The desired port number is already assigned |
0x507 | 1287 | ROUTERERR_NOTREGISTERED | Port not registered |
0x508 | 1288 | ROUTERERR_NOMOREQUEUES | The maximum number of Ports reached |
0x509 | 1289 | ROUTERERR_INVALIDPORT | The port is invalid. |
0x50A | 1290 | ROUTERERR_NOTACTIVATED | TwinCAT Router not active |
0x50B | 1291 | ROUTERERR_FRAGMENTBOXFULL |  |
0x50C | 1292 | ROUTERERR_FRAGMENTTIMEOUT |  |
0x50D | 1293 | ROUTERERR_TOBEREMOVED |  |

General ADS Error Codes

Hex | Dec | Description | Possible Causes | Solution
0x700 | 1792 | error class <device error> |  |
0x701 | 1793 | Service is not supported by server |  |
0x702 | 1794 | invalid index group |  |
0x703 | 1795 | invalid index offset |  |
0x704 | 1796 | reading/writing not permitted |  |
0x705 | 1797 | parameter size not correct |  |
0x706 | 1798 | invalid parameter value(s) |  |
0x707 | 1799 | device is not in a ready state |  |
0x708 | 1800 | device is busy |  |
0x709 | 1801 | invalid context (must be in Windows) |  |
0x70A | 1802 | out of memory |  |
0x70B | 1803 | invalid parameter value(s) |  |
0x70C | 1804 | not found (files, ...) |  |
0x70D | 1805 | syntax error in command or file |  |
0x70E | 1806 | objects do not match |  |
0x70F | 1807 | object already exists |  |
0x710 | 1808 | symbol not found |  |
0x711 | 1809 | symbol version invalid | Onlinechange | Release handle and get a new one
0x712 | 1810 | server is in invalid state |  |
0x713 | 1811 | AdsTransMode not supported |  |
0x714 | 1812 | Notification handle is invalid | Onlinechange | Release handle and get a new one
0x715 | 1813 | Notification client not registered |  |
0x716 | 1814 | no more notification handles |  |
0x717 | 1815 | size for watch too big |  |
0x718 | 1816 | device not initialized |  |
0x719 | 1817 | device has a timeout |  |
0x71A | 1818 | query interface failed |  |
0x71B | 1819 | wrong interface required |  |
0x71C | 1820 | class ID is invalid |  |
0x71D | 1821 | object ID is invalid |  |
0x71E | 1822 | request is pending |  |
0x71F | 1823 | request is aborted |  |
0x720 | 1824 | signal warning |  |
0x721 | 1825 | invalid array index |  |
0x722 | 1826 | symbol not active | Onlinechange | Release handle and get a new one
0x723 | 1827 | access denied |  |
0x724 | 1828 | missing license |  | Activate license for TwinCAT 3 function
0x72c | 1836 | exception occured during system start |  | Check each device transistions
0x740 | 1856 | Error class <client error> |  |
0x741 | 1857 | invalid parameter at service |  |
0x742 | 1858 | polling list is empty |  |
0x743 | 1859 | var connection already in use |  |
0x744 | 1860 | invoke ID in use |  |
0x745 | 1861 | timeout elapsed |  | Check ADS routes of sender and receiver and your firewall setting
0x746 | 1862 | error in win32 subsystem |  |
0x747 | 1863 | Invalid client timeout value |  |
0x748 | 1864 | ads-port not opened |  |
0x750 | 1872 | internal error in ads sync |  |
0x751 | 1873 | hash table overflow |  |
0x752 | 1874 | key not found in hash |  |
0x753 | 1875 | no more symbols in cache |  |
0x754 | 1876 | invalid response received |  |
0x755 | 1877 | sync port is locked |  |

RTime Error Codes

Hex | Dec | Description | Possible Causes
0x1000 | 4096 | RTERR_INTERNAL | Internal fatal error in the TwinCAT real-time system
0x1001 | 4097 | RTERR_BADTIMERPERIODS | Timer value not vaild
0x1002 | 4098 | RTERR_INVALIDTASKPTR | Task pointer has the invalid value ZERO
0x1003 | 4099 | RTERR_INVALIDSTACKPTR | Task stack pointer has the invalid value ZERO
0x1004 | 4100 | RTERR_PRIOEXISTS | The demand task priority is already assigned
0x1005 | 4101 | RTERR_NOMORETCB | No more free TCB (Task Control Block) available. Maximum number of TCBs is 64
0x1006 | 4102 | RTERR_NOMORESEMAS | No more free semaphores available. Maximum number of semaphores is 64
0x1007 | 4103 | RTERR_NOMOREQUEUES | No more free queue available. Maximum number of queue is 64
0x1008 | 4104 | TwinCAT reserved. |
0x1009 | 4105 | TwinCAT reserved. |
0x100A | 4106 | TwinCAT reserved. |
0x100B | 4107 | TwinCAT reserved. |
0x100C | 4108 | TwinCAT reserved. |
0x100D | 4109 | RTERR_EXTIRQALREADYDEF | An external synchronisation interrupt is already applied
0x100E | 4110 | RTERR_EXTIRQNOTDEF | No external synchronsiation interrupt applied
0x100F | 4111 | RTERR_EXTIRQINSTALLFAILED | The apply of the external synchronisation interrupt failed
0x1010 | 4112 | RTERR_IRQLNOTLESSOREQUAL | Call of a service function in the wrong context
0x1017 | 4119 | RTERR_VMXNOTSUPPORTED | Intel VT-x extension is not supported.
0x1018 | 4120 | RTERR_VMXDISABLED | Intel VT-x extension is not enabled in BIOS.
0x1019 | 4121 | RTERR_VMXCONTROLSMISSING | Missing feature in Intel VT-x extension.
0x101A | 4122 | RTERR_VMXENABLEFAILS | Enabling Intel VT-x fails.

TCP Winsock Error Codes

Hex | Dec | Description | Possible Causes | Solution
0x274c | 10060 | A socket operation was attempted to an unreachable host | Host unreachable | Check network connection via ping
0x274d | 10061 | A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond. | Host unreachable | Check network connection via ping
0x2751 | 10065 | No connection could be made because the target machine actively refused it |  |
 |  | Further Winsock error codes: Win32 Error Codes |  |


AdsGetDllVersion

Liefert die Versionnummer, Revisionnummer und die Buildnummer der ADS-DLL zurück.

LONG AdsGetDllVersion(
  void
);

Parameter

-

Rückgabewert

Der Rückgabewert vom Type long enthält in codierter Form die drei oben genannten Angaben über die ADS-DLL.

Beispiel

siehe Beispiel 1.


AdsPortOpen

Stellt eine Verbindung (Kommunikationsport) zum TwinCAT Messagerouter her.

LONG AdsPortOpen(
  void
);

Parameter

-

Rückgabewert

Es wird die Portnummer zurückgegeben, die der ADS-Router dem Programm zugewiesen hat.

Beispiel

siehe Beispiel 2.


AdsPortClose

Die Verbindung (Kommunikationsport) zum TwinCAT Messagerouter wird beendet.

LONG AdsPortClose(
  void
);

Parameter

-

Rückgabewert

Gibt den Fehlerstatus der Funktion zurück.

Beispiel

siehe Beispiel 2.


AdsGetLocalAddress

Liefert die eigene NetId und die eigene Portnummer zurück.

LONG AdsGetLocalAddress(
  PAmsAddr     pAddr
);

Parameter

pAddr

[out] Zeiger auf die Struktur vom Typ AmsAddr.

Rückgabewert

Gibt den Fehlerstatus der Funktion zurück.

Beispiel

siehe Beispiel 2.


AdsSyncWriteReq

Schreibt Daten synchron in ein ADS-Gerät.

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

Parameter

pAddr

[in] Struktur mit NetId und Portnummer vom ADS-Server.

nIndexGroup

[in] Index Group.

nIndexOffset

[in] Index Offset.

nLength

[in] Länge der Daten in Byte, die in den ADS-Server geschrieben werden.

pData

[in] Zeiger auf Daten, die in den ADS-Server geschrieben werden.

Rückgabewert

Gibt den Fehlerstatus der Funktion zurück.

Beispiel

siehe Beispiel 2.


AdsSyncReadReq

Liest Daten synchron aus einem ADS-Server.

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

Parameter

pAddr

[in] Struktur mit NetId und Portnummer vom ADS-Server.

nIndexGroup

[in] Index Group.

nIndexOffset

[in] Index Offset.

nLength

[in] Länge der Daten in Byte.

pData

[out] Zeiger auf Datenbuffer welche die Daten aufnimmt.

Rückgabewert

Gibt den Fehlerstatus der Funktion zurück.

Beispiel

siehe Beispiel 3.


AdsSyncReadReqEx

Liest Daten synchron aus einem ADS-Server.

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

Parameter

pAddr

[in] Struktur mit NetId und Portnummer vom ADS-Server.

nIndexGroup

[in] Index Group.

nIndexOffset

[in] Index Offset.

nLength

[in] Länge der Daten in Byte.

pData

[out] Zeiger auf Datenbuffer welcher die Daten aufnimmt.

pcbReturn

[out] Zeiger auf eine Variable. Diese Variable liefert bei Erfolg die Anzahl der tatsächlich gelesenen Datenbytes zurück.

Rückgabewert

Gibt den Fehlerstatus der Funktion zurück.


AdsSyncReadWriteReq

Schreibt Daten synchron in ein ADS-Server und bekommt von dem ADS-Gerät Daten wieder zurück.

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

Parameter

pAddr

[in] Struktur mit NetId und Portnummer vom ADS-Server.

nIndexGroup

[in] Index Group.

nIndexOffset

[in] Index Offset.

nReadLength

[in] Länge der Daten in Byte, die das ADS-Gerät zurückliefert.

pReadData

[out] Buffer mit Daten, die das ADS-Gerät zurückliefert.

nWriteLength

[in] Länge der Daten in Byte, die in das ADS-Gerät geschrieben werden

pWriteData

[out] Buffer mit Daten, die in das ADS-Gerät geschrieben werden.

Rückgabewert

Gibt den Fehlerstatus der Funktion zurück.

Beispiel

siehe Beispiel 7.


AdsSyncReadWriteReqEx

Schreibt Daten synchron in ein ADS-Server und bekommt von dem ADS-Gerät Daten wieder zurück.

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

Parameter

pAddr

[in] Struktur mit NetId und Portnummer vom ADS-Server.

nIndexGroup

[in] Index Group.

nIndexOffset

[in] Index Offset.

nReadLength

[in] Länge der Daten in Byte, die das ADS-Gerät zurückliefert.

pReadData

[out] Buffer mit Daten, die das ADS-Gerät zurückliefert.

nWriteLength

[in] Länge der Daten in Byte, die in das ADS-Gerät geschrieben werden

pWriteData

[out] Buffer mit Daten, die in das ADS-Gerät geschrieben werden.
pcbReturn

[out] Zeiger auf eine Variable. Diese Variable liefert bei Erfolg die Anzahl der tatsächlich gelesenen Datenbytes zurück.

Rückgabewert

Gibt den Fehlerstatus der Funktion zurück.


AdsSyncReadDeviceInfoReq

Liest die Bezeichnung und die Versionsnummer von einem ADS-Server.

LONG AdsSyncReadDeviceInfoReq(
  PAmsAddr        pAddr,
  PCHAR           pDevName,
  PAdsVersion     pVersion
);

Parameter

pAddr

[in] Struktur mit NetId und Portnummer vom ADS-Server.

pDevName

[out] Zeiger auf eine Zeichenkette, welche den Name von dem ADS-Gerät aufnimmt.

pVersion

[out] Adresse einer Variablen vom Typ AdsVersion, welche die Versionsnummer, Revisionsnummer und die Buildnummer aufnimmt.

Rückgabewert

Gibt den Fehlerstatus der Funktion zurück.

Beispiel

siehe Beispiel 5.


AdsSyncWriteControlReq

Ändert den ADS-Status und den Geräte-Status von einem ADS-Server.

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

Parameter

pAddr

[in] Struktur mit NetId und Portnummer vom ADS-Server.

nAdsState

[in] neuer ADS-Status.

nDeviceState

[in] neuer Geräte-Status.

nLength

[in] Länge der Daten in Byte.

pData

[in] Zeiger auf Daten die zusätzlich zum Ads-Gerät geschickt werden.

Rückgabewert

Gibt den Fehlerstatus der Funktion zurück.

Bemerkungen

Außer dem Ändern von dem ADS-Status und dem Geräte-Status, ist es zusätzlich noch möglich Daten zum ADS-Server zu schicken, um weitere Informationen zu übertragen. Bei den aktuellen ADS-Geräten (PLC, NC, ...) werden diese Daten nicht weiter ausgewertet. Jedes ADS-Gerät kann seinen aktuellen Zustand anderen ADS-Geräten mitteilen. Dabei wird unterschieden zwischen den Status des Gerätes selber (DeviceState) und dem Status der ADS-Schnittstelle von dem ADS-Gerät (AdsState). Die möglichen Zustände, die die ADS-Schnittstelle annehmen kann, ist durch die ADS-Spezifikation festgelegt

Beispiel

siehe Beispiel 6.


AdsSyncReadStateReq

Liest den ADS-Status und den Geräte-Status von einem ADS-Server.

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

Parameter

pAddr

[in] Struktur mit NetId und Portnummer vom ADS-Server.

pAdsState

[out] Adresse einer Variablen, welche den ADS-Status aufnimmt (siehe Datentyp ADSSTATE).

pDeviceState

[out] Adresse einer Variablen, welche den Geräte-Status aufnimmt.

Rückgabewert

Gibt den Fehlerstatus der Funktion zurück.

Anmerkungen

Jedes ADS-Gerät kann seinen aktuellen Zustand anderen ADS-Geräten mitteilen. Dabei wird unterschieden zwischen den Status des Gerätes selber (DeviceState) und dem Status der ADS-Schnittstelle von dem ADS-Gerät (AdsState). Die möglichen Zustände, die die ADS-Schnittstelle annehmen kann, ist durch die ADS-Spezifikation festgelegt.
In Beispiel 11 wird gezeigt, wie mit Hilfe einer Callback-Funktion die Änderung erkannt werden kann.

Beispiel

siehe Beispiel 4.


AdsSyncAddDeviceNotificationReq

Innerhalb eines ADS-Servers (z.B. SPS) wird eine Notification (Bekanntmachung) definiert. Beim Eintreten bestimmter Ereignisse, wird eine Funktion (Callbackfunktion) im ADS-Client (C-Programm) aufgerufen.

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

Parameter

pAddr

[in] Struktur mit NetId und Portnummer vom ADS-Server.

nIndexGroup

[in] IndexGroup.

nIndexOffset

[in] IndexOffset.

pNoteAttrib

[in] Zeiger auf die Struktur, welche weitere Informationen enthält.

pNoteFunc

[in] Name der Callback-Funktion.

hUser

[in] 32-Bit Wert, welcher an die Callback-Funktion übergeben wird.

pNotification

[out] Adresse der Variablen, die den Handle der Notification aufnimmt.

Rückgabewert

Gibt den Fehlerstatus der Funktion zurück.

Limitierung :

Pro ADS-Port steht eine begrenzte Anzahl von 550 Notifikations zur Verfügung.

Anmerkungen

Wird der TwinCAT-Router gestoppt und wieder gestartet, so sind die Notifications ungültig. Mit der Funktion AdsAmsRegisterRouterNotification() können Sie dieses Ereignis abfangen.

Beispiel

siehe Beispiel 8.


AdsSyncDelDeviceNotificationReq

Eine zuvor definierte Notification (Bekanntmachung) wird in einem ADS-Server gelöscht.

LONG AdsSyncDelDeviceNotificationReq(
  PAmsAddr       pAddr,
  ULONG          hNotification
);

Parameter

pAddr

[in] Struktur mit NetId und Portnummer vom ADS-Server.

hNotification

[out] Adresse der Variablen, die den Handle der Notification enthält.

Rückgabewert

Gibt den Fehlerstatus der Funktion zurück.

Beispiel

siehe Beispiel 8.


AdsSyncSetTimeout

Verändert die Timeoutzeit für die ADS-Funktionen. Der Standardwert ist 5000ms.

LONG AdsSyncSetTimeout(
  LONG           nMs
);

Parameter

nMs

[in] Timeoutzeit in ms.

Rückgabewert

Gibt den Fehlerstatus der Funktion zurück.

Beispiel

-


AdsAmsRegisterRouterNotification

Mit Hilfe der Funktion AdsAmsRegisterNotificationReq() kann eine Statusänderung des TwinCAT-Routers erkannt werden. Bei jeder Statusänderung wird die angegebende Callback-Funktion aufgerufen. Durch die Funktion AdsAmsUnRegisterNotification() wird die Statusüberwachung des Routers wieder beendet.

LONG AdsAmsRegisterRouterNotification(
  PAmsRouterNotificationFuncEx   pNoteFunc,
);

Parameter

pNoteFunc

[in] Name der Callback-Funktion

Rückgabewert

Gibt den Fehlerstatus der Funktion zurück.

Bemerkungen:

  • Implementiert ab TcAdsDLL-File-Version: 2.8.0.21 ( ausgeliefert mit TwinCAT 2.9 Build > 941).
  • Eine Verbindung zum TwinCAT-Router kann nur dann aufgebaut werden, wenn auf dem lokalem PC auch TwinCAT installiert wurde. Auf einem System ohne TwinCAT liefert die Funktion einen Fehler zurück.

Beispiel


AdsAmsUnRegisterRouterNotification

Durch die Funktion AdsAmsUnRegisterNotification() wird die Statusüberwachung des TwinCAT-Routers beendet. Siehe auch AdsAmsRegisterNotificationReq().

LONG AdsAmsUnRegisterRouterNotification(
  void
);

Parameter

-

Rückgabewert

Gibt den Fehlerstatus der Funktion zurück.

Bemerkungen:

  • Implementiert ab TcAdsDLL-File-Version: 2.8.0.21 ( ausgeliefert mit TwinCAT 2.9 Build > 941).
  • Eine Verbindung zum TwinCAT-Router kann nur dann aufgebaut werden, wenn auf dem lokalem PC auch TwinCAT installiert wurde. Auf einem System ohne TwinCAT liefert die Funktion einen Fehler zurück.

Beispiel

-


PAmsRouterNotificationFuncEx

Typdefinition der Callback-Funktion, die von der Funktion AdsAmsRegisterRouterNotification benötigt wird.

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


PAdsNotificationFuncEx

Typdefinition der Callback-Funktion, die von der Funktion AdsSyncAddDeviceNotificationReq benötigt wird.

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


Overview

TwinCAT TcAdsDll

Erweiterte Funktionen ( für Multithreaded Applikationen )

Mit den bisherigen Funktionen konnte nur ein Ads-Port pro Prozess kreiert werden. Dies ist vor allem für Mulithreaded Anwendungen nicht ausreichend, da die einzelnen Ads Kommandos sich gegenseitig blockieren. Mit den neuen Funktionen ist es nun möglich mehr als einen Port zu verwenden. Damit könnte z.B. pro Thread ein Ads-Port verwendet werden. Mit Hilfe der Funktion AdsPortOpenEx können neue Ports geöffnet werden. Die zurückgelieferte Port-Nummer wird dann als Parameter an die einzelnen Sync-Funktionen übergeben.


AdsPortOpenEx

Stellt eine Verbindung (Kommunikationsport) zum TwinCAT Messagerouter her. Im Gegensatz zu AdsPortOpen wird jedesmal ein neuer Ads-Port geöffnet. Um mit diesem Port zu kommunizieren, müssen die erweiterten Ads-Funktionen verwendet werden. Diesen Funktionen wird die von AdsPortOpenEx zurückgegebene Port-Nummer als Parameter übergeben. Wenn kein TwinCAT-MessageRouter vorhanden ist wird die Funktion AdsPortOpenEx fehlschlagen.

LONG AdsPortOpenEx(
  void
);

Parameter

-

Rückgabewert

Portnummer des geöffneten Ads-Portes. Eine Rückgabewert von 0 bedeutet, dass der Aufruf fehlgeschlagen ist.

Beispiel

siehe Beispiel 2.


AdsPortCloseEx

Die Verbindung (Kommunikationsport) zum TwinCAT Messagerouter wird beendet. Der Port der geschlossen werden soll, muss vorher durch einen Aufruf von AdsPortOpenEx geöffnet worden sein.

LONG AdsPortCloseEx(
  long nPort
);

Parameter

port

[in] Portnummer eines Ads-Ports, der vorher mit AdsPortOpenEx geöffnet wurde.

Rückgabewert

Gibt den Fehlerstatus der Funktion zurück.

Beispiel

siehe Beispiel 2.


AdsGetLocalAddressEx

Liefert die eigene NetId und die eigene Portnummer zurück.

LONG AdsGetLocalAddressEx(
  long         port,
  PAmsAddr     pAddr
);

Parameter

port

[in] Portnummer eines Ads-Ports, der zuvor mit AdsPortOpenEx oder AdsPortOpen geöffnet worden ist.

pAddr

[out] Zeiger auf die Struktur vom Typ AmsAddr.

Rückgabewert

Gibt den Fehlerstatus der Funktion zurück.

Beispiel

siehe Beispiel 2.


AdsSyncWriteReqEx

Schreibt Daten synchron in ein ADS-Gerät.

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

Parameter

port

[in] Portnummer eines Ads-Ports, der zuvor mit AdsPortOpenEx oder AdsPortOpen geöffnet worden ist.

pAddr

[in] Struktur mit NetId und Portnummer vom ADS-Server.

nIndexGroup

[in] Index Group.

nIndexOffset

[in] Index Offset.

nLength

[in] Länge der Daten in Byte, die in den ADS-Server geschrieben werden.

pData

[in] Zeiger auf Daten, die in den ADS-Server geschrieben werden.

Rückgabewert

Gibt den Fehlerstatus der Funktion zurück.

Beispiel

siehe Beispiel 2.


AdsSyncReadReqEx2

Liest Daten synchron aus einem ADS-Server.

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

Parameter

port

[in] Portnummer eines Ads-Ports, der zuvor mit AdsPortOpenEx oder AdsPortOpen geöffnet worden ist.

pAddr

[in] Struktur mit NetId und Portnummer vom ADS-Server.

nIndexGroup

[in] Index Group.

nIndexOffset

[in] Index Offset.

nLength

[in] Länge der Daten in Byte.

pData

[out] Zeiger auf Datenbuffer welcher die Daten aufnimmt.

pcbReturn

[out] Zeiger auf eine Variable. Diese Variable liefert bei Erfolg die Anzahl der tatsächlich gelesenen Datenbytes zurück.

Rückgabewert

Gibt den Fehlerstatus der Funktion zurück.


AdsSyncReadWriteReqEx2

Schreibt Daten synchron in ein ADS-Server und bekommt von dem ADS-Gerät Daten wieder zurück.

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

Parameter

port

[in] Portnummer eines Ads-Ports, der zuvor mit AdsPortOpenEx oder AdsPortOpen geöffnet worden ist.

pAddr

[in] Struktur mit NetId und Portnummer vom ADS-Server.

nIndexGroup

[in] Index Group.

nIndexOffset

[in] Index Offset.

nReadLength

[in] Länge der Daten in Byte, die das ADS-Gerät zurückliefert.

pReadData

[out] Buffer mit Daten, die das ADS-Gerät zurückliefert.

nWriteLength

[in] Länge der Daten in Byte, die in das ADS-Gerät geschrieben werden

pWriteData

[out] Buffer mit Daten, die in das ADS-Gerät geschrieben werden.
pcbReturn

[out] Zeiger auf eine Variable. Diese Variable liefert bei Erfolg die Anzahl der tatsächlich gelesenen Datenbytes zurück.

Rückgabewert

Gibt den Fehlerstatus der Funktion zurück.


AdsSyncReadDeviceInfoReqEx

Liest die Bezeichnung und die Versionsnummer von einem ADS-Server.

LONG AdsSyncReadDeviceInfoReqEx(
  LONG         	port,
  PAmsAddr        pAddr,
  PCHAR           pDevName,
  PAdsVersion     pVersion
);

Parameter

port

[in] Portnummer eines Ads-Ports, der zuvor mit AdsPortOpenEx oder AdsPortOpen geöffnet worden ist.

pAddr

[in] Struktur mit NetId und Portnummer vom ADS-Server.

pDevName

[out] Zeiger auf eine Zeichenkette, welche den Name von dem ADS-Gerät aufnimmt.

pVersion

[out] Adresse einer Variablen vom Typ AdsVersion, welche die Versionsnummer, Revisionsnummer und die Buildnummer aufnimmt.

Rückgabewert

Gibt den Fehlerstatus der Funktion zurück.

Beispiel

siehe Beispiel 5.


AdsSyncWriteControlReqEx

Ändert den ADS-Status und den Geräte-Status von einem ADS-Server.

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

Parameter

port

[in] Portnummer eines Ads-Ports, der zuvor mit AdsPortOpenEx oder AdsPortOpen geöffnet worden ist.

pAddr

[in] Struktur mit NetId und Portnummer vom ADS-Server.

nAdsState

[in] neuer ADS-Status.

nDeviceState

[in] neuer Geräte-Status.

nLength

[in] Länge der Daten in Byte.

pData

[in] Zeiger auf Daten die zusätzlich zum Ads-Gerät geschickt werden.

Rückgabewert

Gibt den Fehlerstatus der Funktion zurück.

Bemerkungen

Außer dem Ändern von dem ADS-Status und dem Geräte-Status, ist es zusätzlich noch möglich Daten zum ADS-Server zu schicken, um weitere Informationen zu übertragen. Bei den aktuellen ADS-Geräten (PLC, NC, ...) werden diese Daten nicht weiter ausgewertet. Jedes ADS-Gerät kann seinen aktuellen Zustand anderen ADS-Geräten mitteilen. Dabei wird unterschieden zwischen den Status des Gerätes selber (DeviceState) und dem Status der ADS-Schnittstelle von dem ADS-Gerät (AdsState). Die möglichen Zustände, die die ADS-Schnittstelle annehmen kann, ist durch die ADS-Spezifikation festgelegt

Beispiel

siehe Beispiel 6.


AdsSyncReadStateReqEx

Liest den ADS-Status und den Geräte-Status von einem ADS-Server.

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

Parameter

port

[in] Portnummer eines Ads-Ports, der zuvor mit AdsPortOpenEx oder AdsPortOpen geöffnet worden ist.

pAddr

[in] Struktur mit NetId und Portnummer vom ADS-Server.

pAdsState

[out] Adresse einer Variablen, welche den ADS-Status aufnimmt (siehe Datentyp ADSSTATE).

pDeviceState

[out] Adresse einer Variablen, welche den Geräte-Status aufnimmt.

Rückgabewert

Gibt den Fehlerstatus der Funktion zurück.

Anmerkungen

Jedes ADS-Gerät kann seinen aktuellen Zustand anderen ADS-Geräten mitteilen. Dabei wird unterschieden zwischen den Status des Gerätes selber (DeviceState) und dem Status der ADS-Schnittstelle von dem ADS-Gerät (AdsState). Die möglichen Zustände, die die ADS-Schnittstelle annehmen kann, ist durch die ADS-Spezifikation festgelegt.
In Beispiel 11 wird gezeigt, wie mit Hilfe einer Callback-Funktion die Änderung erkannt werden kann.

Beispiel

siehe Beispiel 4.


AdsSyncAddDeviceNotificationReqEx

Innerhalb eines ADS-Servers (z.B. SPS) wird eine Notification (Bekanntmachung) definiert. Beim Eintreten bestimmter Ereignisse, wird eine Funktion (Callbackfunktion) im ADS-Client (C-Programm) aufgerufen.

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

Parameter

port

[in] Portnummer eines Ads-Ports, der zuvor mit AdsPortOpenEx oder AdsPortOpen geöffnet worden ist.

pAddr

[in] Struktur mit NetId und Portnummer vom ADS-Server.

nIndexGroup

[in] IndexGroup.

nIndexOffset

[in] IndexOffset.

pNoteAttrib

[in] Zeiger auf die Struktur, welche weitere Informationen enthält.

pNoteFunc

[in] Name der Callback-Funktion.

hUser

[in] 32-Bit Wert, welcher an die Callback-Funktion übergeben wird.

pNotification

[out] Adresse der Variablen, die den Handle der Notification aufnimmt.

Rückgabewert

Gibt den Fehlerstatus der Funktion zurück.

Limitierung :

Pro ADS-Port steht eine begrenzte Anzahl von 550 Notifikations zur Verfügung.

Anmerkungen

Wird der TwinCAT-Router gestoppt und wieder gestartet, so sind die Notifications ungültig. Mit der Funktion AdsAmsRegisterRouterNotification() können Sie dieses Ereignis abfangen.

Beispiel

siehe Beispiel 8.


AdsSyncDelDeviceNotificationReqEx

Eine zuvor definierte Notification (Bekanntmachung) wird in einem ADS-Server gelöscht.

LONG AdsSyncDelDeviceNotificationReqEx(
  LONG           port,
  PAmsAddr       pAddr,
  ULONG          hNotification
);

Parameter

port

[in] Portnummer eines Ads-Ports, der zuvor mit AdsPortOpenEx oder AdsPortOpen geöffnet worden ist.

pAddr

[in] Struktur mit NetId und Portnummer vom ADS-Server.

hNotification

[out] Adresse der Variablen, die den Handle der Notification enthält.

Rückgabewert

Gibt den Fehlerstatus der Funktion zurück.

Beispiel

siehe Beispiel 8.


AdsSyncSetTimeoutEx

Verändert die Timeoutzeit für die ADS-Funktionen. Der Standardwert ist 5000ms.

LONG AdsSyncSetTimeoutEx(
  LONG           port,
  LONG           nMs
);

Parameter

port

[in] Portnummer eines Ads-Ports, der zuvor mit AdsPortOpenEx oder AdsPortOpen geöffnet worden ist.

nMs

[in] Timeoutzeit in ms.

Rückgabewert

Gibt den Fehlerstatus der Funktion zurück.

Beispiel

-


AdsSyncGetTimeoutEx

Liefert die eingestellte Timeoutzeit für die ADS-Funktionen. Der Standardwert ist 5000ms.

LONG AdsSyncGetTimeoutEx(
  LONG           port,
  LONG*          pnMs
);

Parameter

port

[in] Portnummer eines Ads-Ports, der zuvor mit AdsPortOpenEx oder AdsPortOpen geöffnet worden ist.

pnMs

[out] Puffer für die Timeoutzeit in ms.

Rückgabewert

Gibt den Fehlerstatus der Funktion zurück.

Beispiel

-


AdsAmsPortEnabledEx

Liefert den Status der ADS-Client-Verbindung.

LONG AdsAmsPortEnabledEx(
  LONG           nPort,
  BOOL*          pbEnabled
);

Parameter

nPort

[in] Portnummer eines Ads-Ports, der zuvor mit AdsPortOpenEx oder AdsPortOpen geöffnet worden ist.

pbEnabled

[out] Puffer für den Statuswert.

Rückgabewert

Gibt den Fehlerstatus der Funktion zurück.

Beispiel

-


AmsAddr

In dieser Struktur kann die vollständige Adresse eines ADS-Gerätes abgelegt werden.

typedef struct {
  AmsNetId        netId;
  USHORT          port;
} AmsAddr, *PAmsAddr;

Elemente

NetId

NetId.

port

Portnummer.


AmsNetId

Die NetId eines ADS-Gerätes kann in dieser Struktur dargestellt werden.

typedef struct {
  UCHAR        b[6];
} AmsNetId, *PAmsNetId;

Elemente

b[6]

NetId, bestehend aus 6 Ziffern.

Bemerkung

Die Struktur besteht aus einem Array mit 6 Elementen vom Typ UCHAR. Jedes Element des Arrays darf die Werte von 1 bis 255 annehmen. Die NetId wird mit dem TwinCAT System Service eingestellt.


AdsVersion

Die Struktur beinhaltet die Versionsnummer, Revisionsnummer und Buildnummer.

typedef struct {
  UCHAR           version;
  UCHAR           revision;
  USHORT          build;
} AdsVersion, *PAdsVersion;

Elemente

version

Versionsnummer.

revision

Revisionsnummer.

build

Buildnummer.


AdsNotificationAttrib

Diese Struktur beinhaltet bei der Definition einer Notification sämtliche Attribute.

typedef struct {
  ULONG           cbLength;
  ADSTRANSMODE    nTransMode;
  ULONG           nMaxDelay;
  ULONG           nCycleTime;
} AdsNotificationAttrib, *PAdsNotificationAttrib;

Elemente

cbLength

Länge der Daten, die an die Callback-Funktion übergeben werden sollen.

nTransMode

ADSTRANS_SERVERCYCLE: Die Callback-Funktion der Notification wird zyklisch aufgerufen.

ADSTRANS_SERVERONCHA: Die Callback-Funktion der Notification wird nur bei Änderung des Wertes aufgerufen.

nMaxDelay

Spätestens nach dieser Zeit wird die Callback-Funktion der Notification aufgerufen. Die Einheit ist in 100ns.

nCycleTime

In diesem Zeitinvall prüft der ADS-Server, ob sich die Variable verändert hat. Die Einheit ist in 100ns

Anmerkungen

Die Übertragung zwischen der Echtzeit und der ADS-DLL wird durch einen FIFO gepuffert. Jeder Wert, der per Callback-Funktion übertragen werden soll, wird zuvor von TwinCAT in den FIFO geschrieben. Ist der Puffer voll, oder ist die Zeit nMaxDelay abgelaufen, so wird für jeden Eintrag die Callback-Funktion aufgerufen. Dabei wird durch den Parameter nTransMode das Verhalten in folgender Weise beeinflußt:

ADSTRANS_SERVERCYCLE
Es werden in dem Zeitintervall nCycleTime die Werte zyklisch in den FIFO geschrieben. Der kleinste mögliche Wert für nCycleTime, ist die Zykluszeit des Ads-Servers; bei der SPS ist dieses die Zykluszeit der Task. Die Cycletime kann in 1ms-Schritten ausgewertet werden. Geben Sie als Cycletime 0ms an, so wird in jedem Zyklus der Task der Wert in den FIFO geschrieben.

ADSTRANS_SERVERONCHA
Es wird nur dann ein Wert in den FIFO geschrieben, wenn sich dieser geändert hat. Die Abtastung in der Echtzeit erfolgt in der Zeit, die in nCycleTime angegeben wird. Die Cycletime kann in 1ms-Schritten ausgewertet werden. Geben Sie als Cycletime 0ms an, so wird bei jeder Änderung die Variablen in den FIFIO geschrieben.

Achtung: Durch zu viele Leseoperationen kann das System so stark ausgelastet werden, daß die Bedieneroberfläche stark verlangsamt wird.

Tip: Setzen Sie die Cycletime auf möglichst angemessene Werte und beenden Sie jedesmal Verbindungen, wenn diese nicht mehr benötigt werden.


AdsNotificationHeader

Diese Struktur wird an die Callback-Funktion mit übergeben.

typedef struct {
  ULONG           hNotification;
  __int64         nTimeStamp;
  ULONG           cbSampleSize;
  UCHAR           data[ANYSIZE_ARRAY];
} AdsNotificationHeader, *PAdsNotificationHeader;

Elemente

hNotification

Handel der Notification. Wird beim definieren der Notification festgelegt;

nTimeStamp

Zeitstempel in FILETIME-Format.

cbSampleSize

Anzahl der Bytes die übertragen wurden.

data[ANY_SIZE_ARRAY]

Array mit den übertragenden Daten.

Bemerkung

Der Zeitstempel wird im FILETIME-Format übertragen. FILETIME ist eine 64-Bit Variable, welche in 100ns Schritten die Uhrzeit und das Datum beginnend vom 01.01.1601 darstellt. Die lokale Zeitverschiebung wird nicht berücksichtigt; es wird die Coordinated Universal Time (UTC) benutzt. Wollen Sie auf einzelne Elemente (Tag, Monat, Jahr, Stunde, Minute, Sekunde, usw.) zugreifen, müssen Sie den Zeitstempel vom FILETIME-Format in das SYSTEMTIME-Format umwandeln und anschließend die Zeit, unter Berücksichtigung des örtlichen Standorts (local time), umrechnen.

Beispiel

siehe Beispiel 8.


ADSSTATE

typedef enum nAdsState {
  ADSSTATE_INVALID	= 0,
  ADSSTATE_IDLE		= 1,
  ADSSTATE_RESET		= 2,
  ADSSTATE_INIT		= 3,
  ADSSTATE_START		= 4,
  ADSSTATE_RUN		= 5,
  ADSSTATE_STOP		= 6,
  ADSSTATE_SAVECFG	= 7,
  ADSSTATE_LOADCFG	= 8,
  ADSSTATE_POWERFAILURE	= 9,
  ADSSTATE_POWERGOOD	= 10,
  ADSSTATE_ERROR		= 11,
  ADSSTATE_SHUTDOWN	= 12,
  ADSSTATE_SUSPEND	= 13,
  ADSSTATE_RESUME		= 14,
  ADSSTATE_CONFIG		= 15,	// system is in config mode
  ADSSTATE_RECONFIG	= 16,	// system should restart in config mode
  ADSSTATE_MAXSTATES
} ADSSTATE;


ADSTRANSMODE

typedef enum nAdsTransMode {
  ADSTRANS_NOTRANS		= 0,
  ADSTRANS_CLIENTCYCLE	= 1,
  ADSTRANS_CLIENT1REQ	= 2,
  ADSTRANS_SERVERCYCLE	= 3,
  ADSTRANS_SERVERONCHA	= 4
} ADSTRANSMODE;


Übersicht

Die TcAdsDll stellt Funktionen zur Kommunikation mit anderen ADS Geräten über die COM Schnittstelle des TwinCAT-Routers zu Verfügung. Weitere Informationen zu ADS finden Sie unter TwinCAT ADS.
Die COM Klasse TcClient unterstützt die Anwenderprogramme, eine Verbindung von einem ADS Gerät zum lokalen PC oder zu einem Remote PC aufzubauen. Die TcAdsDll unterstützt ein multi-threaded Einwählmodell. Sie kann von multi-threaded und single-threaded COM clients verwendet werden. Wenn die TcAdsDll von single-threaded COM clients benutzt wird, werden die Methodenaufrufe durch einen Ordner synchronisiert. Der Ordner ist in der TcAdsDll kompiliert, es ist keine weitere proxy-stub-dll notwendig.
Der TcClient gibt für jede einzelne Verbindung zu einem ADS Gerät ein Objekt vom Type TcAdsSync zurück. Diese Klasse unterstützt die synchrone ADS Kommunikation zum ADS Gerät. Die Klasse TcAdsSync stellt die Funktionen über die Default Schnittstelle ITcAdsSync zur Verfügung. Um die ADS Notification vom TcAdsSync Objekt zu erreichen, muss das Anwenderprogramm die Event Schnittstelle ITcAdsSyncEvent implementieren und verbinden.


CoClasses

TwinCAT Object Server: CoClasses

TcAdsDll::Classes

Die TcAdsDll stellt eine Schnittstelle nach außen durch COM (Component Object Model) zur Verfügung.

CoClasses | Beschreibung
TcClient | Die Haupt-Klasse der TcAdsDll. Unterstützt eine class factory um eine ADS client Verbindung herzustellen.


TcClient

Das Objekt TcClient stellt eine class factory zur Erstellung einer ADS client Verbindung zur Verfügung.

Schnittstelle | Beschreibung
ITcClient | Schnittstelle unterstützt eine class factory


TcAdsSync

Das Objekt TcAdsSync unterstützt die ADS Kommunikation zu einem ADS Gerät. TcAdsSync hat keine class factory und kann nur durch einen Aufruf erstellt werden.

An ITcClient::Connect

Schnittstelle | Beschreibung
ITcAdsSync | Schnittstelle, die die ADS Kommunikations-Funktionen bereitstellt.


ITcClient

Die ITcClient Schnittstelle stellt eine class factory zum Erstellen eines Objektes zur Kommunikation mit einem ADS Gerät zur Verfügung. Die Schnittstelle leitet sich von IUnknown ab.

IUnknown Methoden | Beschreibung
QueryInterface | Gibt einen Pointer zur Schnittstelle zurück, die angefragt wurde.
AddRef | Inkrementiert den Referenzzähler
Release | Dekrementiert den Referenzzähler

ITcClient Methoden | Beschreibung
Connect | Erstellt ein Objekt vom Typ ITcAdsSync, dass die synchrone ADS Kommunikation zu einem einzelnen ADS Gerät unterstützt.

Anmerkungen


ITcClient::Connect

Erstellt eine neues ADS client Kommunikations-Objekt für ein einzelnes ADS Gerät durch eine vorgegebene AdsNet Id und Port Nummer.

HRESULT Connect(AmsNetId* pAmsNetId, long nPort, ITcAdsSync** pipTcAdsSync);

Parameter

pAmsNetId
[in] Variable präsentiert die Ams Net Id durch den Structurtyp AmsNetId. Wenn die Net Id auf 0.0.0.0.0.0 gesetzt ist, wird die Verbindung zum lokalen TwinCAT System hergestellt. Wenn auf dem Client PC kein TWinCAt System installiert ist, benutzt die Verbindung TCP/IP. Die Einschränkung bei der TCP/IP Verbindung ist, dass der Client nur Verbindungen zum Haupt Remote Gerät mit der AMS Net Id = TCP/IP address + 1.1. herstellen kann.
nPort
[in] ADS Port Nummer des ADS Geräts, mit dem kommuniziert werden soll.
ITcAdsSync
[out, retval] Gibt einen Pointer zu einem ITcAdsSync Pointer zurück, der das Objekt enthält, das für die ADS Kommunikation verwendet wird.

Rückgabe Werte

S_OK
Die Verbindungsfunktion wurde erfolgreich aufgerufen.
ADSERRORCODES
Ein Fehler tritt auf.

Anmerkungen

Um eine Verbindung zu einem Remote TwinCAT System herzustellen, muss das Remote Gerät auf die Liste der Remote Computer im TwinCAT System hinzugefügt werden. Wenn auf dem Client PC und dem Remote PC ein TwinCAT System installiert ist, muss der Client PC in die Liste der Remote Computer im Remote PC eingetragen werden und umgekehrt. Wenn auf dem Client PC kein TwinCAT System installiert ist, muss der Client PC nur in die Liste der Remote Computer im Remote PC eingetragen werden. In diesem Fall besteht die AMS Net Id lediglich aus der TCP/IP Adresse + 1.1. .


ITcAdsSync

TwinCAT TcAdsDll: COM Interfaces

Übersicht: ITcAdsSync

Die ITcClient Schnittstelle stellt einem Client die Funktionalität zur Kommunikation mit einem ADS Gerät zur Verfügung. Die Schnittstelle leitet sich von IUnknown ab.

IUnknown Methoden | Beschreibung
QueryInterface | Gibt einen Pointer zur angefragten Schnittstelle zurück
AddRef | Inkrementiert den Referenzzähler
Release | Dekrementiert den Referenzzähler

ITcAdsSync Methoden und Eigenschaften | Beschreibung
Write | Schreibt einen Wert an eine Variable in einem ADS Gerät als Bytestream.
Read | Liest den Wert einer Variable aus einem ADS Gerät als Bytestream.
ReadWrite | Schreibt einen Wert an ein ADS Gerät und liest das Ergebnis in einem Schritt.
WriteControl | Setzt den Status des ADS Systems und Geräts.
AddDeviceNotification | Verbindet eine Variable mit dem Client. Der Client wird durch ein Event angezeigt.
DelDeviceNotification | Entfernt die Verbindung einer Variablen.
ReadDeviceInfo | Liest Geräte Informationen aus dem ADS Gerät.
ReadState | Liest den Status des ADS Geräts.
Timeout | Setzt die Zeit, nach der der Client eine Timeout Warnung von allen übrigen ADS Kommandos erhält.

Anmerkungen


ITcAdsSync::Write

Schreibt einen Wert an eine Variable in einem ADS Gerät als Bytestream.

HRESULT Write(indexGroup, indexOffset, cbLen, pData);

Parameter

indexGroup
[in] Variable vom Typ long die die Index Group der Variable, auf die geschrieben werden soll, enthält.
indexOffset
[in] Variable vom Typ long die den Index Offset der Variable, auf die geschrieben werden soll, enthält.
cbLen
[in] Anzahl der Bytes die in die Variable geschrieben werden sollen.
pData
[in, size_is(cbLen)] Pointer auf das erste Element eines Bytearrays mit der Länge cbLen der Daten, die auf eine Variable in einem ADS Gerät geschrieben werden sollen.

Rückgabe Werte

S_OK
Die Funktion wurde erfolgreich aufgerufen.
ADSERRORCODES
Ein Fehler tritt auf.

Anmerkungen


ITcAdsSync::Read

Liest den Wert einer Variable aus einem ADS Gerät als Bytestream.

HRESULT Read(long indexGroup, long indexOffset, long cbLen, long* pcbRead, [out, size_is(cbLen), length_is(*pcbRead)] byte* pData);

Parameter

indexGroup
[in] Variable vom Typ long die die Index Group der Variable, die gelesen werden soll, enthält.
indexOffset
[in] Variable vom Typ long die den Index Offset der Variable, die gelesen werden soll, enthält.
cbLen
[in] Anzahl der Bytes die aus der Variable gelesen werden sollen.
pcbRead
[out] Pointer auf eine Variable, die die Anzahl der (wirklich) gelesenen Bytes zurückgibt.
pData
[out, size_is(cbLen), length_is(*pcbRead)] Pointer auf das erste Element eines Bytearrays mit der Länge cbLen der Daten, die aus einer Variable in einem ADS Gerät gelesen werden sollen.

Rückgabe Werte

S_OK
Die Funktion wurde erfolgreich aufgerufen.
ADSERRORCODES
Ein Fehler tritt auf.

Anmerkungen


ITcAdsSync::ReadWrite

Schreibt einen Wert an ein ADS Gerät und liest das Ergebnis in einem Schritt.

HRESULT ReadWrite(long indexGroup, long indexOffset, long cbRdLen, long* pcbRead, byte* pRdData, [in] long cbWrLen, [in, size_is(cbWrLen)] byte* pWrData);

Parameter

indexGroup
[in] Variable vom Typ long die die Index Group der Variable, die gelesen werden soll, enthält.
indexOffset
[in] Variable vom Typ long die den Index Offset der Variable, die gelesen werden soll, enthält.
cbRdLen
[in] Anzahl der Bytes die aus der Variable gelesen werden sollen.
pcbRead
[out] Pointer auf eine Variable, die die Anzahl der (wirklich) gelesenen Bytes zurückgibt.
pRdData
[out, size_is(cbRdLen), length_is(*pcbRead)] Pointer auf das erste Element eines Bytearrays mit der Länge cbRdLen der Daten, die aus einer Variable in einem ADS Gerät gelesen werden sollen.
cbWrLen
[in] Anzahl der Bytes die in die Variable geschrieben werden sollen.
pWrData
[in, size_is(pWrData)] Pointer auf das erste Element eines Bytearrays mit der Länge cbRdLen der Daten, die auf eine Variable in einem ADS Gerät geschrieben werden sollen.

Rückgabe Werte

S_OK
Die Funktion wurde erfolgreich aufgerufen.
ADSERRORCODES
Ein Fehler tritt auf.

Anmerkungen


ITcAdsSync::WriteControl

Setzt den Status des ADS Systems und Geräts.

HRESULT WriteControl(ADSSTATE adsState, ADSSTATE deviceState, long cbLen, byte* pData);

Parameters

adsState
[in] Der Status als ADSSTATE, der in das ADS system geschrieben werden soll.
deviceState
[in] Der Status als ADSSTATE, der in das ADS Gerät geschrtieben werden soll.
cbLen
[in] Anzahl der Bytes die in die Variable geschrieben werden sollen.
pData
[in, size_is(cbLen)] Pointer auf das erste Element eines Bytearrays mit der Länge cbLen der zusätzlichen Daten die in das ADS Gerät geschrieben werden sollen.

Rückgabe Werte

S_OK
Die Funktion wurde erfolgreich aufgerufen.
ADSERRORCODES
Ein Fehler tritt auf.

Anmerkungen


ITcAdsSync::AddDeviceNotification

Verbindet eine Variable mit dem Client. Der Client wird durch ein Event angezeigt.

HRESULT AddDeviceNotification(long indexGroup, long indexOffset,
long cbLenData, ADSTRANSMODE transMode,
long nMaxDelay, long nCycleTime, long* phNotification);

Parameter

indexGroup
[in] Variable vom Typ long die die Index Group der Variable, auf die geschrieben werden soll, enthält.
indexOffset
[in] Variable vom Typ long die den Index Offset der Variable, auf die geschrieben werden soll, enthält.
cbLenData
[in] Anzahl der Bytes die aus der verbundenen Variable gelesen werden sollen.
transMode
[out] Modus, wie die Variable mit dem Typ ADSTRANSMODE verbunden ist.
nMaxDelay
[in] Die Zeit mit einer Auflösung von 100 ns nach der ein callback der implementierten _ITcAdsSyncEvent Schnittstelle erwartet wird.
nCycleTime

[in] Die Zeit mit einer Auflösung von 100 ns , wie die Variable gesammelt werden soll.
phNotification
[out, retval] Pointer auf das Handle, das allein die Verbindung zur Variablen kennzeichnet.

Rückgabe Werte

S_OK
Die Funktion wurde erfolgreich aufgerufen.
ADSERRORCODES
Ein Fehler tritt auf.

Anmerkungen

Eine nCycleTime= 10000 und nMaxDelay=100000 würde alle 10 ms 10 Werte mit der Auflösung von 1 ms erhalten.


ITcAdsSync::DelDeviceNotification

Entfernt die Verbindung einer Variablen, die vorher mit einer AddDeviceNotification hergestellt wurde.

HRESULT DelDeviceNotification(long hNotication);

Parameter

phNotification
[in] Handle der vorher aufgebauten Verbindung.

Rückgabe Werte

S_OK
Die Funktion wurde erfolgreich aufgerufen.
ADSERRORCODES
Ein Fehler tritt auf.

Anmerkungen

Eine nCycleTime= 10000 und nMaxDelay=100000 würde alle 10 ms 10 Werte mit der Auflösung von 1 ms erhalten.


ITcAdsSync::ReadDeviceInfo

Liest Geräte Informationen aus dem ADS Gerät.

HRESULT ReadDeviceInfo(BSTR* pName, AdsVersion* pVersion);

Parameter

pName
[out] Variable die den BSTR String, der das ADS Gerät beschreibt, enthält.
pVersion
[out] Pointer auf eine Variable des Types AdsVersion , welche die Versionsnummer enthält.

Rückgabe Werte

S_OK
Die Funktion wurde erfolgreich aufgerufen.
ADSERRORCODES
Ein Fehler tritt auf.

Anmerkungen


ITcAdsSync::ReadState

Liest den Status des ADS Geräts und des ADS Systems.

HRESULT ReadState(ADSSTATE* pAdsState, ADSSTATE* pDeviceState);

Parameter

pAdsState
[out] Pointer auf eine Variable des Typs ADSSTATE die den Status des ADS Systems enthält.
pDeviceState
[out] Pointer auf eine Variable des Typs ADSSTATE die den Status des ADS Geräts enthält.

Rückgabe Werte

S_OK
Die Funktion wurde erfolgreich aufgerufen.
ADSERRORCODES
Ein Fehler tritt auf.

Anmerkungen


ITcAdsSync::Timeout

Diese Eigenschaft wird benutzt, um den Timeout Wert in Millisekunden für alle ADS Funktionen der ITcAdsSync Schnittstelle zuzuweisen oder abzurufen.

Abrufen des Timeout Wertes.

HRESULT get_Timeout(long *pTime);

Parameters

pTime
[out, retval] Pointer auf eine Variable die den aktuellen Timeout Wert enthält.

Rückgabe Werte

S_OK
Die Funktion wurde erfolgreich aufgerufen.
ADSERRORCODES
Ein Fehler tritt auf.

Neuen Timeout Wert zuweisen

HRESULT put_Timeout(long nTime);

Parameter

pTime
[in] Variable die den neuen Timeout Wert enthält.

Rückgabe Werte

S_OK
Die Funktion wurde erfolgreich aufgerufen.
ADSERRORCODES
Ein Fehler tritt auf.

Anmerkungen


_ITcAdsSyncEvent

TwinCAT TcAdsDll: COM Interfaces

Übersicht: _ITcAdsSyncEvent

Die _ITcAdsSyncEvent Schnittstelle ist die Event Schnittstelle, die ein Client implementieren muss, wenn er eine ADS Notification für verbundene Variablen bekommen will. Die Schnittstelle leitet sich von IUnknown ab.

IUnknown Methoden | Beschreibung
QueryInterface | Gibt einen Pointer zur angefragten Schnittstelle zurück
AddRef | Inkrementiert den Referenzzähler
Release | Dekrementiert den Referenzzähler

_ITcAdsSyncEvent Methoden | Beschreibung
DeviceNotification | Diese Methode wird vom Server für alle verbundenen Variablen dieses ADS Geräts aufgerufen

Anmerkungen


_ITcAdsSyncEvent::DeviceNotification

Diese Methode wird vom Server für alle verbundenen Variablen dieses ADS Geräts aufgerufen. Das Event tritt für solche Variablen auf, die vorher durch eine AddDeviceNotification verbunden wurden.

HRESULT DeviceNotification([in]TimeStamp* pTime, [in] long hNotification, [in] long cbLen, [in, size_is(cbLen)]byte* pData );

Parameter

pTime
[in] Pointer auf eine Variable des Typs TimeStamp die die genaue Zeit enthält, zu der die verbundene Variable gesammelt wurde.
hNotification
[in] Handle, das eine einzelne verbundene Variable identifiziert. Das Handle wurde zurückgegeben, wenndie Variable durch einen Aufruf der Methode AddDeviceNotification verbunden wurde.
cbLen
[in] Anzahl der Bytes die durch diese Methode empfangen wurden.
pData
[in, size_is(cbLen)]. Pointer auf das erste Element eines Bytearrays mit der Länge cbLen das die Daten der verbundenen Variablen enthält

Rückgabe Werte

S_OK
Die Funktion wurde erfolgreich aufgerufen.
ADSERRORCODES
Ein Fehler tritt auf.

Anmerkungen


AdsVersion

Die Struktur AdsVersion stellt die Versionsnummer dar, aufgesplittet in Version, Revision und Build Nummer.

struct AdsVersion
{
BYTE version;
BYTE revision;
short build;
}

Anmerkungen


TimeStamp

Die Struktur TimeStamp stellt eine Windows FILETIME Datenstruktur dar. Es handelt sich um einen 64bit Wert, der die Anzahl der 100-Nanosekunden Intervalle seit dem 1. Januar 1601 angibt.

Durch dieses Mittel legt Win32 das Datum und die Zeit fest.

struct TimeStamp
{
long nLow;
long nHigh;
};

Anmerkungen


ADS Error Codes

TwinCAT TcAdsDll: COM Error Codes

ADSERRORCODES

Die Aufzählung des Typs ADSERRORCODE beschreibt ADS Fehlercodes mit den folgenden Werten:

Konst. | Hex Wert | Beschreibung
ADS_E_ERROR | 0x98117000 | Offset des ADS Fehlers übergeben von COM HRESULT
ADS_E_SRVNOTSUPP | 0x98117001 | angefragter Service wird vom ADS Gerät nicht unterstützt.
_E_INVALIDGRP | 0x98117002 | ungültige index group
ADS_E_INVALIDOFFSET | 0x98117003 | ungültiger index offset
ADS_E_INVALIDACCESS | 0x98117004 | Lesen und Schreiben nicht erlaubt
ADSERR_DEVICE_INVALIDSIZE | 0x98117005 | Parametergröße ist nicht korrekt
ADS_E_INVALIDDATA | 0x98117006 | ungültige(r) Datenwert(e)
ADS_E_NOTREADY | 0x98117007 | Gerät ist nicht bereit
ADS_E_BUSY | 0x98117008 | Gerät beschäftigt
ADS_E_INVALIDCONTEXT | 0x98117009 | ungültiger Kontext
ADS_E_NOMEMORY | 0x9811700A | Speicherplatz unzureichend (out of memory)
ADS_E_INVALIDPARM | 0x9811700B | ungültige Parameterwerte
ADS_E_NOTFOUND | 0x9811700C | nicht gefunden (Dateien, ...)
ADS_E_SYNTAX | 0x9811700D | Syntaxfehler in Befehl oder Datei
ADS_E_INCOMPATIBLE | 0x9811700E | Objekte nicht kompatibel
ADS_E_EXISTS | 0x9811700F | Objekt existiert bereits
ADS_E_SYMBOLNOTFOUND | 0x98117010 | Symbol nicht gefunden
ADS_E_SYMBOLVERSIONINVALID | 0x98117011 | Symbolversion ungültig
ADS_E_INVALIDSTATE | 0x98117012 | Server befindet sich im ungültigen Status
ADS_E_TRANSMODENOTSUPP | 0x98117013 | AdsTransMode nicht unterstützt
ADS_E_NOTIFYHNDINVALID | 0x98117014 | Notification handle ist ungültig
ADS_E_CLIENTUNKNOWN | 0x98117015 | Notification client ist nicht registriert
ADS_E_NOMOREHDLS | 0x98117016 | Keine weiteren notification handles
ADS_E_INVALIDWATCHSIZE | 0x98117017 | Zu große Größe für Watch
ADS_E_NOTINIT | 0x98117018 | Gerät ist nicht initialisiert
ADS_E_TIMEOUT | 0x98117019 | Gerät hat ein timeout
ADS_E_NOINTERFACE | 0x9811701A | Anfrage an Schnittstelle gescheitert
ADS_E_INVALIDINTERFACE | 0x9811701B | falsche Schnittstelle erforderlich
ADS_E_INVALIDCLSID | 0x9811701C | class ID ungültig
ADS_E_INVALIDOBJID | 0x9811701D | object ID ungültig
ADS_E_CLIENT_ERROR | 0x98117040 | Fehler class: client Fehler
ADS_E_CLIENT_INVALIDPARM | 0x98117041 | ungültiger Parameter bei Serviceaufruf
ADS_E_CLIENT_LISTEMPTY | 0x98117042 | Polling Liste ist leer
ADS_E_CLIENT_VARUSED | 0x98117043 | var connection bereits in Benutzung
ADS_E_CLIENT_DUPLINVOKEID | 0x98117044 | invoke id In Benutzung
ADS_E_CLIENT_SYNCTIMEOUT | 0x98117045 | timeout verstrichen
ADS_E_CLIENT_W32ERROR | 0x98117046 | Fehler im Win32 Subsystem
ADS_E_CLIENT_TIMEOUTINVALID | 0x98117047 |
ADS_E_CLIENT_PORTNOTOPEN | 0x98117048 |
ADS_E_CLIENT_NOAMSADDR | 0x98117049 |
ADS_E_CLIENT_SYNCINTERNAL | 0x98117050 | Interner Fehler in ADS Sync
ADS_E_CLIENT_ADDHASH | 0x98117051 | hash table overflow
ADS_E_CLIENT_REMOVEHASH | 0x98117052 | key nicht in hash table gefunden
ADS_E_CLIENT_NOMORESYM | 0x98117053 | Keine weiteren Symbole im Speicher


ADSSTATE

Die Aufzählung des Typs ADSSTATE beschreibt den ADS Status mit den folgenden Werten:

Konst | Int Wert | Beschreibung
ADSSTATE_INVALID | 0 | Ungültiger Status
ADSSTATE_IDLE | 1 | Idles Status
ADSSTATE_RESET | 2 | Reset Status
ADSSTATE_INIT | 3 | initialisiert
ADSSTATE_START | 4 | gestartet
ADSSTATE_RUN | 5 | läuft
ADSSTATE_STOP | 6 | gestoppt
ADSSTATE_SAVECFG | 7 | Gesicherte Konfiguration
ADSSTATE_LOADCFG | 8 | Geladene Konfiguration
ADSSTATE_POWERFAILURE | 9 | Spannungsausfall
ADSSTATE_POWERGOOD | 10 | Spannung vorhanden
ADSSTATE_ERROR | 11 | Fehlerstatus
ADSSTATE_SHUTDOWN | 12 | Herunterfahren (Shut down)
ADSSTATE_SUSPEND | 13 | verschoben
ADSSTATE_RESUME | 14 | wiederaufgenommen
ADSSTATE_CONFIG | 15 | system is in config mode
ADSSTATE_RECONFIG | 16 | system should restart in config mode


ADSSTATE

TwinCAT TcAdsDll: COM Error Codes

ADSTRANSMODE

Die Aufzählung des Typs ADSTRANSMODE beschreibt den Betrieb einer Geräte notification mit den folgenden Werten:

Konst | Int Wert | Beschreibung
ADSTRANS_NOTRANS | 0 |
ADSTRANS_CLIENTCYCLE | 1 |
ADSTRANS_CLIENTONCHA | 2 |
ADSTRANS_SERVERCYCLE | 3 |
ADSTRANS_SERVERONCHA | 4 |
ADSTRANS_CLIENT1REQ | 5 |


TcAdsDllCe Overview

TwinCAT TcAdsDllCe

TcAdsDllCe

Die TcAdsDllCe erlaubt ADS-Kommunikation über TCP/IP auf Windows CE Geräten.

Die TcAdsDllCe unterstützt die Plattform Pocket PC 3.0 und Handheld PC 2000 auf folgenden Geräten:

Prozessor | Installations-Dateien
StrongARM | setup\TcAdsDllCe.StrongARM.CAB
MIPS | setup\TcAdsDllCe.MIPS.CAB
Intel I486 compatible | setup\TcAdsDllCe.I486.CAB
Intel Pentium compatible | setup\TcAdsDllCe.I586.CAB

Um die TcAdsDllCe.dll auf ihrem Gerät zu installieren, sind folgende Schritte durchzuführen:

  • Mit Hilfe des Explorers und Active Sync die entsprechende TcAdsDllCe.XXX.CAB in das Verzeichnis \Windows\Start Menu ihres CE Gerätes kopieren.
  • Auf dem CE-Gerät die Datei TcAdsDllCe.XXX.CAB vom Start Menu aus starten.
  • Danach kann die Datei wieder entfernt werden.


TcAdsDllCE Samples Übersicht

TwinCAT TcAdsDLL: CE Beispiele

Übersicht

Beschreibung | Quelltexte
Beispiel 1: Auslesen einer SPS-Variablen | AdsReadTestPPC01.exe
Beispiel 2: Wert in eine SPS-Variable schreiben | AdsWriteTestPPC01.exe
Beispiel 3: Zugriff per Variablenname | AdsReadWriteTestPPC01.exe
Beispiel 4: Ergeigniesgesteuertes lesen | AdsDNotificTestPPC01.exe


TcAdsDllCe Setupe

TwinCAT TcAdsDllCe

Einbindung in Embedded Visual C++

Um die TcAdsDllCe in ihrem Embedded Visual C++ Projekt zu verwenden, müssen Sie folgende Schritte durchführen:

  • Project Settings Dialog öffnen
  • Link Tab auswählen und im Editierfeld Object/library modules die für ihren Prozessortyp spezifische Bibliothek auswählen:

- StrongArm: TwinCATDirectory\ADS Api\AdsDllCe\lib\arm\TcAdsDllCe.lib

- MIPS: StrongArm: TwinCATDirectory\ADS Api\AdsDllCe\lib\mips\TcAdsDllCe.lib

- X86: TwinCATDirectory\ADS Api\TcAdsDllCe\lib\x86\TcAdsDllCe.lib

Die Methoden der TcAdsDllCE.dll sind ansonsten kompatibel zur TcAdsDll.dll.