TcAdsClient Class
ADS Client / ADS Communication object.
Inheritance Hierarchy
System.Object
TwinCAT.Ads.TcAdsClient
Namespace: TwinCAT.Ads
Assembly: TwinCAT.Ads (in TwinCAT.Ads.dll)
Version: 4.3.0.0
Syntax
C#
public class TcAdsClient : ITcAdsRpcInvoke,
IDisposable, IAdsConnection, IConnection, IConnectionStateProvider, IAdsNotifications,
IAdsAnyAccess, IAdsHandleAccess
VB
Public Class TcAdsClient
Implements ITcAdsRpcInvoke, IDisposable, IAdsConnection, IConnection,
IConnectionStateProvider, IAdsNotifications, IAdsAnyAccess, IAdsHandleAccess
The TcAdsClient type exposes the following members.
Constructors
|
|
Name |
Description |
|---|---|---|
|
|
Initializes a new instance of the class TcAdsClient. | |
|
|
Initializes a new instance of the TcAdsClient class. |
Properties
|
|
Name |
Description |
|---|---|---|
|
|
Gets the AmsAddress of the ADS server (Target side) | |
|
|
Get the AmsAddress of the ADS client (Source side) | |
|
|
Determines, whether the TcAdsClient is disposed | |
|
|
Gets the TcAdsClient Identifier. | |
|
|
Gets a value indicating whether the local ADS port was opened successfully. It does not indicate if the target port is available. Use the method ReadState to determine if the target port is available. | |
|
|
Gets a value indicating whether the ADS client is connected to a ADS Server on the local computer. | |
|
|
Gets actual ADS Transport protocol | |
|
|
Gets the current state of the local AMS Router. | |
|
|
Gets the session that initiated this IConnection | |
|
|
Gets or sets a value indicating whether the TcAdsClient object synchronizes the incoming notifications (obsolete) | |
|
|
Sets the timeout for the ads communication. Unit is in ms. |
Methods
|
|
Name |
Description |
|---|---|---|
|
|
AddDeviceNotification(String, AdsStream, AdsTransMode, Int32, Int32, Object) |
Connects a variable to the ADS client. The ADS client will be notified by the AdsNotification event. |
|
|
AddDeviceNotification(String, AdsStream, AdsTransMode, TimeSpan, TimeSpan, Object) |
Connects a variable to the ADS client. The ADS client will be notified by the AdsNotification event. |
|
|
AddDeviceNotification(UInt32, UInt32, AdsStream, AdsTransMode, Int32, Int32, Object) |
Connects a variable to the ADS client. The ADS client will be notified by the AdsNotification event. |
|
|
AddDeviceNotification(UInt32, UInt32, AdsStream, AdsTransMode, TimeSpan, TimeSpan, Object) |
Connects a variable to the ADS client. The ADS client will be notified by the AdsNotification event. |
|
|
AddDeviceNotification(String, AdsStream, Int32, Int32, AdsTransMode, Int32, Int32, Object) |
Connects a variable to the ADS client. The ADS client will be notified by the AdsNotification event. |
|
|
AddDeviceNotification(String, AdsStream, Int32, Int32, AdsTransMode, TimeSpan, TimeSpan, Object) |
Connects a variable to the ADS client. The ADS client will be notified by the AdsNotification event. |
|
|
AddDeviceNotification(UInt32, UInt32, AdsStream, Int32, Int32, AdsTransMode, Int32, Int32, Object) |
Connects a variable to the ADS client. The ADS client will be notified by the AdsNotification event. |
|
|
Connects a variable to the ADS client. The ADS client will be notified by the AdsNotification event. | |
|
|
AddDeviceNotificationEx(String, AdsTransMode, Int32, Int32, Object, Type) |
Connects a variable to the ADS client. The ADS client will be notified by the AdsNotification event. |
|
|
AddDeviceNotificationEx(String, AdsTransMode, TimeSpan, TimeSpan, Object, Type) |
Connects a variable to the ADS client. The ADS client will be notified by the AdsNotification event. |
|
|
AddDeviceNotificationEx(String, AdsTransMode, Int32, Int32, Object, Type, .Int32.) |
Connects a variable to the ADS client. The ADS client will be notified by the AdsNotification event. |
|
|
AddDeviceNotificationEx(String, AdsTransMode, TimeSpan, TimeSpan, Object, Type, .Int32.) |
Connects a variable to the ADS client. The ADS client will be notified by the AdsNotification event. |
|
|
AddDeviceNotificationEx(UInt32, UInt32, AdsTransMode, Int32, Int32, Object, Type) |
Connects a variable to the ADS client. The ADS client will be notified by the AdsNotification event. |
|
|
AddDeviceNotificationEx(UInt32, UInt32, AdsTransMode, TimeSpan, TimeSpan, Object, Type) |
Connects a variable to the ADS client. The ADS client will be notified by the AdsNotification event. |
|
|
AddDeviceNotificationEx(UInt32, UInt32, AdsTransMode, Int32, Int32, Object, Type, .Int32.) |
Connects a variable to the ADS client. The ADS client will be notified by the AdsNotification event. If type is a string type, the first element of the parameter args specifies the number of characters of the string. If type is an array type, the number of elements for each dimension has to be specified in the parameter args. At the moment only 1 dimensional Arrays are supported. |
|
|
AddDeviceNotificationEx(UInt32, UInt32, AdsTransMode, TimeSpan, TimeSpan, Object, Type, .Int32.) |
Connects a variable to the ADS client. The ADS client will be notified by the AdsNotification event. If type is a string type, the first element of the parameter args specifies the number of characters of the string. If type is an array type, the number of elements for each dimension has to be specified in the parameter args. At the moment only 1 dimensional Arrays are supported. |
|
|
Closes this IConnection | |
|
|
Establishes a connection to a ADS device using the local netID. | |
|
|
Establishes a connection to a ADS device. | |
|
|
Establishes a connection to a ADS device. | |
|
|
Establishes a connection to a ADS device. | |
|
|
Establishes a connection to a ADS device. | |
|
|
Establishes a connection to a ADS device. | |
|
|
Obsolete. Creates a new instance of the TcAdsSymbolInfoLoader class (Symbol Browser V1, obsolete). | |
|
|
Generates a unique handle for an ADS variable. | |
|
|
Deletes an existing notification. | |
|
|
Releases the handle of a ADS variable again. | |
|
|
Disconnects the TcAdsClient | |
|
|
Releases the resources used by TcAdsClient. | |
|
|
Disposes the TcAdsClient. | |
|
|
Determines whether the specified object is equal to the current object. (Inherited from Object.) | |
|
|
Finalizes an instance of the TcAdsClient class. (Overrides Object.Finalize..) | |
|
|
Serves as the default hash function. (Inherited from Object.) | |
|
|
Gets the Type of the current instance. (Inherited from Object.) | |
|
|
Invokes the specified RPC Method | |
|
|
Invokes the RPC method. | |
|
|
Invokes the specified RPC Method | |
|
|
Invokes the RPC method. | |
|
|
Creates a shallow copy of the current Object. (Inherited from Object.) | |
|
|
Called when before the TcAdsClient is disconnected. | |
|
|
Called when the ConnectionState of the TcAdsClient has changed. | |
|
|
Reads data synchronously from an ADS device and writes it to the given stream. | |
|
|
Reads data synchronously from an ADS device and writes it to the given stream. | |
|
|
Reads data synchronously from an ADS device and writes it to the given stream. | |
|
|
Reads data synchronously from an ADS device and writes it to the given stream. | |
|
|
Reads data synchronously from an ADS device and writes it to the given stream. | |
|
|
Reads data synchronously from an ADS device and writes it to an object. | |
|
|
Reads data synchronously from an ADS device and writes it to an object. | |
|
|
Reads data synchronously from an ADS device and writes it to an object. | |
|
|
Reads data synchronously from an ADS device and writes it to an object. | |
|
|
Reads the string. | |
|
|
Reads the string | |
|
|
Reads the identification and version number of an ADS server. | |
|
|
Reads the ADS status and the device status from an ADS server. | |
|
|
Reads the value of a symbol and returns it as an object. Strings and all primitive datatypes(UInt32, Int32, Bool etc.) are supported. Arrays and structures cannot be read. | |
|
|
Reads the value of a symbol and returns the value as object. The parameter type must have the same layout as the ADS symbol. | |
|
|
Call this method to obtain information about the individual symbols (variables) in ADS devices. | |
|
|
Writes data synchronously to an ADS device and then Reads data from this device. | |
|
|
ReadWrite(Int32, AdsStream, Int32, Int32, AdsStream, Int32, Int32) |
Writes data synchronously to an ADS device and then Reads data from this device. |
|
|
ReadWrite(UInt32, UInt32, .Byte., Int32, Int32, .Byte., Int32, Int32) |
Writes data synchronously to an ADS device and then Reads data from this device. |
|
|
ReadWrite(UInt32, UInt32, AdsStream, Int32, Int32, AdsStream, Int32, Int32) |
Writes data synchronously to an ADS device and then Reads data from this device. |
|
|
Returns a string that represents the current object. (Inherited from Object.) | |
|
|
Connects a variable to the ADS client. The ADS client will be notified by the AdsNotification event. | |
|
|
Connects a variable to the ADS client. The ADS client will be notified by the AdsNotification event. | |
|
|
Deletes an existing notification. | |
|
|
Invokes the specified RPC Method | |
|
|
Tries to invoke the RPC method. | |
|
|
Invokes the specified RPC Method | |
|
|
Tries to invoke a RPC method. | |
|
|
Reads data synchronously from an ADS device and writes it to the given stream. | |
|
|
Reads data synchronously from an ADS device and writes it to the given stream. | |
|
|
Reads data synchronously from an ADS device and writes it to the given stream. | |
|
|
Reads data synchronously from an ADS device and writes it to the given stream. | |
|
|
Reads the ADS status and the device status from an ADS server. Unlike the ReadState method this method does not call an exception on failure. Instead an AdsErrorCode is returned. If the return value is equal to AdsErrorCode.NoError the call was successfull. | |
|
|
TryReadWrite(Int32, .Byte., Int32, Int32, .Byte., Int32, Int32, Int32.) |
Writes data synchronously to an ADS device and then Reads data from this device. |
|
|
TryReadWrite(Int32, AdsStream, Int32, Int32, AdsStream, Int32, Int32, Int32.) |
Writes data synchronously to an ADS device and then Reads data from this device. |
|
|
TryReadWrite(UInt32, UInt32, .Byte., Int32, Int32, .Byte., Int32, Int32, Int32.) |
Writes data synchronously to an ADS device and then Reads data from this device. |
|
|
TryReadWrite(UInt32, UInt32, AdsStream, Int32, Int32, AdsStream, Int32, Int32, Int32.) |
Writes data synchronously to an ADS device and then Reads data from this device. |
|
|
Writes data synchronously to an ADS device. | |
|
|
Writes data synchronously to an ADS device. | |
|
|
Writes data synchronously to an ADS device. | |
|
|
Changes the ADS status and the device status of an ADS server. | |
|
|
Changes the ADS status and the device status of an ADS server. | |
|
|
Trigger Client Method/Command. | |
|
|
Writes data synchronously to an ADS device. | |
|
|
Trigger Client Method/Command. | |
|
|
Writes data synchronously to an ADS device. | |
|
|
Writes data synchronously to an ADS device. | |
|
|
Writes data synchronously to an ADS device. | |
|
|
Writes data synchronously to an ADS device. | |
|
|
Writes data synchronously to an ADS device. | |
|
|
Writes data synchronously to an ADS device. | |
|
|
Writes data synchronously to an ADS device. | |
|
|
Writes an object synchronously to an ADS device. | |
|
|
Writes an object synchronously to an ADS device. | |
|
|
Writes an object synchronously to an ADS device. | |
|
|
Writes an object synchronously to an ADS device. | |
|
|
Writes the string (Potentially unsafe!) | |
|
|
Writes the string (Potentially unsafe!) | |
|
|
Changes the ADS status and the device status of an ADS server. | |
|
|
Changes the ADS status and the device status of an ADS server. | |
|
|
Writes a value to the symbol. Strings and all primitive data types(UInt32, Int32, Bool etc.) are supported. Array and structures are not supported. If a string is passed as parameter, the method attempts to parse the string according to the ADS data type of the symbol. | |
|
|
Writes the passed object value to the specified ADS symbol.The parameter type must have the same layout as the ADS symbol. |
Events
|
|
Name |
Description |
|---|---|---|
|
|
Occurs when the ADS device sends a ADS Notification to the client. | |
|
|
Occurs when a exception has occurred during notification management. | |
|
|
Occurs when the ADS devices sends an (extended) notification to the client. | |
|
|
Occurs when the ADS state changes. | |
|
|
Occurs when the symbol version has been changed changes. | |
|
|
Occurs when the state of the local Router has changed. | |
|
|
Occurs when the connection state has been changed. |
Extension Methods
|
|
Name |
Description |
|---|---|---|
|
|
Overloaded. Gets an observable sequence of AdsStates via Polling. (Defined by AdsClientExtensions.) | |
|
|
Overloaded. Gets an observable sequence of AdsStates via Polling. (Defined by AdsClientExtensions.) | |
|
|
Overloaded. Polls the symbol values on timepoints where the polling observable streams data / triggers (Defined by AnyTypeExtensions.) | |
|
|
Overloaded. Polls the symbol as value sequence of object values with a specified period time. (Defined by AnyTypeExtensions.) | |
|
|
Overloaded. Polls the symbol as value sequence of object values with a specified period time. (Defined by AnyTypeExtensions.) | |
|
|
PollValues(String, Type, IObservable.Unit., Func.Exception, Object.) |
Overloaded. Polls the symbol values on timepoints where the polling observable streams data / triggers (Defined by AnyTypeExtensions.) |
|
|
Overloaded. Polls the symbol as value sequence of object values with a specified period time. (Defined by AnyTypeExtensions.) | |
|
|
PollValues(String, Type, .Int32., IObservable.Unit., Func.Exception, Object.) |
Overloaded. Polls the symbol values on time points where the polling observable streams data / triggers (Defined by AnyTypeExtensions.) |
|
|
PollValues(String, Type, .Int32., TimeSpan, Func.Exception, Object.) |
Overloaded. Polls the symbol as value sequence of object values with a specified period time. (Defined by AnyTypeExtensions.) |
|
|
Overloaded. Polls the symbol values on timepoints where the polling observable streams data / triggers (Defined by AnyTypeExtensions.) | |
|
|
Overloaded. Polls the symbol as value sequence of object values with a specified period time. (Defined by AnyTypeExtensions.) | |
|
|
PollValues.T.(String, IObservable.Unit., Func.Exception, T.) |
Overloaded. Polls the symbol values on timepoints where the polling observable streams data / triggers (Defined by AnyTypeExtensions.) |
|
|
Overloaded. Polls the symbol as value sequence of object values with a specified period time. (Defined by AnyTypeExtensions.) | |
|
|
Overloaded. Polls the symbol values on time points where the polling observable streams data / triggers (Defined by AnyTypeExtensions.) | |
|
|
Overloaded. Polls the symbol as value sequence of object values with a specified period time. (Defined by AnyTypeExtensions.) | |
|
|
PollValues.T.(String, .Int32., IObservable.Unit., Func.Exception, T.) |
Overloaded. Polls the symbol values on timepoints where the polling observable streams data / triggers (Defined by AnyTypeExtensions.) |
|
|
PollValues.T.(String, .Int32., TimeSpan, Func.Exception, T.) |
Overloaded. Polls the symbol as value sequence of object values with a specified period time. (Defined by AnyTypeExtensions.) |
|
|
Gets an observable sequence of AdsStates. (Defined by AdsClientExtensions.) | |
|
|
Overloaded. Gets an observable sequence of Notifications. (Defined by AdsClientExtensions.) | |
|
|
Overloaded. Gets an observable sequence of Notification objects. (Defined by AdsClientExtensions.) | |
|
|
Overloaded. Gets an observable sequence of Notifications. (Defined by AdsClientExtensions.) | |
|
|
Overloaded. Gets an observable sequence of Notification objects. (Defined by AdsClientExtensions.) | |
|
|
Observable sequence of Values driven by ADS Notifications on the specified symbol. (Defined by ValueSymbolExtensions.) | |
|
|
Overloaded. Writes the sequence of values to the symbol specified by the instance path. (Defined by AnyTypeExtensions.) | |
|
|
Overloaded. Writes the sequence of values to the symbol specified by the instance path. (Defined by AnyTypeExtensions.) |
Remarks
IMPORTANT: The Default setting of the Synchronize property has changed to 'false' from Version 4.2.XX on. This has the effect that - by default - the notifications events and are not synchronized into the UI thread anymore. To re enable the obsolete behavior set to 'true'. AdsNotification AdsNotificationEx Synchronize Use an instance of this object to create a point-to-point send/receive connection to an ADS Server/Device object. The class TcAdsClient is a wrapper for the TcAdsdll.dll and enables synchronous/asynchronous access to data of an ADS Device.
Examples
The following sample shows how to instantiate and use the TcAdsClient class.
TcAdsClient Demo
using System;
using System.Threading;
using TwinCAT.Ads;
using TwinCAT.TypeSystem;
using TwinCAT.TypeSystem.Generic;
namespace Sample
{
class AdsClient
{
/// <summary>
/// Defines the entry point of the application.
/// </summary>
/// <param name="args">The arguments.</param>
static void Main(string[] args)
{
AmsAddress address = ArgParser.Parse(args);
using (TcAdsClient client = new TcAdsClient())
{
// Asynchronized access necessary for Console applications
client.Synchronize = false;
// Connect to Address
client.Connect(address.NetId,address.Port); // Connect to Port (851, first PLC by default)
// Read the identification and version number of the device
DeviceInfo deviceInfo = client.ReadDeviceInfo();
Version version = deviceInfo.Version.ConvertToStandard();
Console.WriteLine(string.Format("DeviceName: {0}", deviceInfo.Name));
Console.WriteLine(string.Format("DeviceVersion: {0}", version.ToString(3)));
// Read the state of the device
StateInfo stateInfo = client.ReadState();
AdsState state = stateInfo.AdsState;
short deviceState = stateInfo.DeviceState;
Console.WriteLine(string.Format("DeviceState: {0}", deviceState));
Console.WriteLine(string.Format("AdsState : {0}", state));
// Write ADS Commands (write state) to target
// Set PLC to Run
if (state == AdsState.Stop)
{
StateInfo setState = new StateInfo(AdsState.Run, 0);
client.WriteControl(setState);
}
//create variable handle for Plc Project Name (automatic generated symbol in PLC)
int handleProjectName = client.CreateVariableHandle("TwinCAT_SystemInfoVarList._AppInfo.ProjectName");
int handleNotification = 0; // Notification Handle for Task1 CycleCount changes
try
{
// Read value from target and Marshal data into string
using (AdsBinaryReader reader = new AdsBinaryReader(new AdsStream(256)))
{
int read = client.Read(handleProjectName, (AdsStream)reader.BaseStream);
string projectName = reader.ReadPlcAnsiString(256);
Console.WriteLine(string.Format("ProjectName : {0}", projectName));
}
_notificationStream = new AdsStream(4); // Sizeof UDINT
_notificationReader = new AdsBinaryReader(_notificationStream);
client.AdsNotification += client_NotificationEvent; // Register for Notification event
//Register Notification for Task1 CycleCount symbol (automatic generated symbol in PLC)
handleNotification = client.AddDeviceNotification("TwinCAT_SystemInfoVarList._TaskInfo[1].CycleCount", _notificationStream, AdsTransMode.OnChange, 500, 0, null);
// Sleep 10 Seconds to receive events
System.Threading.Thread.Sleep(10000);
}
finally
{
// Cleanup all handles
// Dispose all Streams
client.DeleteDeviceNotification(handleNotification);
_notificationReader.Close();
_notificationStream.Close();
// Always delete all variable handles.
client.DeleteVariableHandle(handleProjectName);
}
Console.WriteLine("");
Console.WriteLine("Press [Enter] for leave:");
Console.ReadLine();
}
}
Argument Parser
public static class ArgParser
{
/// <summary>
/// Parses the arguments.
/// </summary>
/// <param name="args">The arguments.</param>
/// <returns>AmsAddress.</returns>
public static AmsAddress Parse(string[] args)
{
AmsNetId netId = AmsNetId.Local;
int port = 851;
if (args != null)
{
if (args.Length > 0 && args[0] != null)
netId = AmsNetId.Parse(args[0]);
if (args.Length > 1 && args[1] != null)
port = int.Parse(args[1]);
}
return new AmsAddress(netId, port);
}
}
The following sample shows how to call (Remote Procedures / Methods) within the PLC directly from the TcAdsClient class.
RPC Call Example
namespace Sample
{
using System;
using System.Diagnostics;
using TwinCAT.Ads;
using TwinCAT.TypeSystem;
class RpcCallV1Program
{
/// <summary>
/// Defines the entry point of the application.
/// </summary>
/// <param name="args">The arguments.</param>
static void Main(string[] args)
{
//Parse the AmsAddress from command-line arguments
AmsAddress address = ArgParser.Parse(args);
// Create the ADS Client
using (TcAdsClient client = new TcAdsClient())
{
// Establish Connection
client.Connect(address);
// Call a Method that has the following signature (within MAIN Program)
/* {attribute 'TcRpcEnable'}
METHOD PUBLIC M_Add : INT
VAR_INPUT
i1 : INT := 0;
i2 : INT := 0;
END_VAR
*/
short result = (short)client.InvokeRpcMethod("MAIN", "M_Add", new object[] {(short)1, (short)4});
// Call a Method that has no parameter and returns VOID
client.InvokeRpcMethod("MAIN", "M_Method1", new object[] {});
}
}
}
}