IMlpiConnection Interface Reference

Inherits IDispatch.

Collaboration diagram for IMlpiConnection:

Public Types
typedef struct IMlpiConnection::Version	Version
typedef struct IMlpiConnection::ConnectionInfo	ConnectionInfo

Public Member Functions
HRESULT	Connect ([in] BSTR address)
HRESULT	Disconnect (void)
HRESULT	TestConnection ([in] LONG payload, [in] LONG numMeasurements, [out, retval] struct ConnectionInfo *connectInfo)
HRESULT	Delay ([in] LONG delayMilliseconds)
HRESULT	GetClientCoreVersion ([out, retval] struct Version *versionInfo)
HRESULT	GetServerCoreVersion ([out, retval] struct Version *versionInfo)

Properties
VARIANT_BOOL	IsConnected [get]
ISystem	System [get]
IMotion	Motion [get]
ILogic	Logic [get]
IParameter	Parameter [get]
IWatchdog	Watchdog [get]
IIo	Io [get]
ITrace	Trace [get]
IContainer	Container [get]
IRobot	Robot [get]

Detailed Description

Definition of the IMlpiConnection interface which is the root object of a connection to a MLPI Device.

The IMlpiConnection class is the root object of the MLPI object hierarchy. It represents a single connection to a device that supports the MLPI. The MlpiConnection class contains properties and subobjects which contain further MLPI methods.

Definition at line 76 of file IMlpiConnection.idl.

Member Typedef Documentation

IMlpiConnection::Version

Describes the API version information. The build number counts continuously within a major release, all other elements count at the beginning, if a higher element will be incremented.

Elements of struct Version

Type	Element	Description
LONG	major	Major release, changes of interfaces, behavior or significant changes of code may occur.
LONG	minor	Minor release, new features or a significant set of bug fixes may occur.
LONG	bugfix	Bug fixes of existing features.
LONG	patch	Patch of an existing release.
LONG	build	Build number.

IMlpiConnection::ConnectionInfo

This structure is used by the function TestConnection to return the results of the timing measurements.

Elements of struct ConnectionInfo

Type	Element	Description
DOUBLE	minimum	Minimum time duration of all measurements.
DOUBLE	maximum	Maximum time duration of all measurements.
DOUBLE	average	Average time duration of all measurements.
DOUBLE	variance	Variance of all measurements.
DOUBLE	standardDeviation	Standard deviation of all measurements.

Member Enumeration Documentation

enum IMlpiConnection::Type

This enumeration defines the basic types of as used by the MLPI.

Enumerator
TYPE_INVALID	invalid or not supported type
TYPE_CHAR	1 byte signed integer
TYPE_UCHAR	1 byte unsigned integer
TYPE_SHORT	2 byte signed integer
TYPE_USHORT	2 byte unsigned integer
TYPE_LONG	4 byte signed integer
TYPE_ULONG	4 byte unsigned integer
TYPE_LLONG	8 byte signed integer
TYPE_ULLONG	8 byte unsigned integer
TYPE_FLOAT	4 byte floating point
TYPE_DOUBLE	4 byte floating point
TYPE_CHAR_ARRAY	1 byte signed integer array
TYPE_UCHAR_ARRAY	1 byte unsigned integer array
TYPE_SHORT_ARRAY	2 byte signed integer array
TYPE_USHORT_ARRAY	2 byte unsigned integer array
TYPE_LONG_ARRAY	4 byte signed integer array
TYPE_ULONG_ARRAY	4 byte unsigned integer array
TYPE_LLONG_ARRAY	8 byte signed integer array
TYPE_ULLONG_ARRAY	8 byte unsigned integer array
TYPE_FLOAT_ARRAY	4 byte floating point array
TYPE_DOUBLE_ARRAY	4 byte floating point array
TYPE_BOOL8	1 byte boolean
TYPE_BOOL8_ARRAY	1 byte boolean array
TYPE_CHAR_UTF8	string with 1 byte per character
TYPE_CHAR_UTF16	string with 2 bytes per character
TYPE_CHAR_UTF8_ARRAY	string array with 1 byte per character
TYPE_CHAR_UTF16_ARRAY	string array with 2 bytes per character

Definition at line 81 of file IMlpiConnection.idl.

Member Function Documentation

HRESULT IMlpiConnection::Connect

(

[in] BSTR

address

)

This function connects the user application with a MLPI Device. The first argument is used to specify the target device to which you want to connect. This can either be a control running on the same physical device as your application or a control that is connected via a network, for example, by TCP/IP. In this case, you have to give the IP or host name of the target.

It is also possible to set additional options in the connect string as an argument list.

• address=value IP or URL path of connection.
• timeout_connect=value Timeout used for connecting in milliseconds.
• timeout_send=value Timeout used for sending data to target in milliseconds.
• timeout_receive=value Timeout used for receiving data from target in milliseconds.
• auto_reconnect=value If set to 1 or 'true', then the MLPI will try to reconnect with each new call of any MLPI function after connection was lost. For connecting, the same timeout settings are used as given for the first connect.
• user=value Login name of user. See Permission and user management for more information about user and permission system.
• password=value Password of user.

A timeout value of 0 means that the timeout value should be chosen automatically by the operating system.

Parameters

[in]

address

Address identifying the control. Use an IP address to connect over Ethernet to another control.

Returns

Return value indicating success (>=0) or error (<0).

Example C#:

try
{
  MlpiConnection connection = new MlpiConnection();

  // connect to control with ip address 192.168.0.17
  connection.Connect("192.168.0.17");

  // read current diagnosis text of the target device
  Console.WriteLine("Diagnosis Text: " + connection.System.GetDisplayedDiagnosis().text);

  // disconnect from control
  connection.Disconnect();
}
catch (System.Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

Example VBA:

Dim connection As MlpiConnection
Set connection = New MlpiConnection

' connect to device with ip address
connection.Connect "192.168.0.17"

' retrieve and show the name of the device
MsgBox connection.System.GetName

' disconnect from control
connection.Disconnect

Note:

This method maps to the mlpiCore function mlpiApiConnect, where you can find further documentation.

HRESULT IMlpiConnection::Disconnect

(

void

)

This function disconnects the user application from the MlpiConnection. After closing the MLPI connection, no more method calls to the MLPI device can be made.

Returns

Return value indicating success (>=0) or error (<0).

Note:

This method maps to the mlpiCore function mlpiApiDisconnect, where you can find further documentation.

HRESULT IMlpiConnection::TestConnection	(	[in] LONG	payload,
		[in] LONG	numMeasurements,
		[out, retval] struct ConnectionInfo *	connectInfo
	)

This function performs a benchmark on the MLPI communication mechanism. Use it to measure the duration of a MLPI function call with the given payload in bytes. The resulting timing values are the durations which are necessary to marshal the payload, send the payload to the MLPI server, unmarshal it on the MLPI server, perform the remote procedure call, marshal the results, send them back to the MLPI client unmarshal them again and return them to the client thread program. These are the basic costs needed for nearly every MLPI call.

Parameters

[in]	payload	Payload in number of bytes that is used for the MLPI communication to be measured.
[in]	numMeasurements	Number of measurements to do for calculating the average resulting timing values.
[out]	connectInfo	Pointer to structure which receives the calculated timing values.

Returns

Return value indicating success (>=0) or error (<0).

Example C#:

try
{
  // run 50 iterations with 100 byte payload to measure the connection speed
  ConnectionInfo info = connection.TestConnection(100, 50);

  // print info to console
  Console.WriteLine("Average:  " + info.average * 0.001 + " ms");
  Console.WriteLine("Minimum:  " + info.minimum * 0.001 + " ms");
  Console.WriteLine("Maximum:  " + info.maximum * 0.001 + " ms");
  Console.WriteLine("Variance: " + info.variance * 0.001 * 0.001 + " ms^2");
  Console.WriteLine("Standard Deviation: " + info.standardDeviation * 0.001 + " ms");
}
catch (System.Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

Note:

This method maps to the mlpiCore function mlpiApiTestConnection, where you can find further documentation.

HRESULT IMlpiConnection::Delay

(

[in] LONG

delayMilliseconds

)

This function does a simple delay on the server side. All this function performs is a blocking delay on the server side in the given amount of milliseconds. Use it during development or debugging of your application to simulate high traffic on your network. This way, you can test the behavior of your client application when MLPI communication slows down. The delay has no impact on the performance of the control.

Parameters

[in]

delayMilliseconds

Delay in milliseconds to block.

Returns

Return value indicating success (>=0) or error (<0).

Example C#:

try
{
  // block on server side for 1 second
  connection.Delay(1000);
}
catch (System.Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

Note:

This method maps to the mlpiCore function mlpiApiDelay, where you can find further documentation.

HRESULT IMlpiConnection::GetClientCoreVersion

(

[out, retval] struct Version *

versionInfo

)

This function returns the version info of the MLPI client library. No connection to the server is needed to execute this method.

Parameters

[out]

versionInfo

Pointer to struct receiving the version info.

Returns

Return value indicating success (>=0) or error (<0).

Example C#:

try
{
  // read the version info. Client Version can be called without established connection
  commlpiLib.Version version = connection.GetClientCoreVersion();

  // print to console
  Console.WriteLine("Major:  " + version.major);
  Console.WriteLine("Minor:  " + version.minor);
  Console.WriteLine("Bugfix:  " + version.bugfix);
  Console.WriteLine("Patch:  " + version.patch);
  Console.WriteLine("Build:  " + version.build);
}
catch (System.Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

Note:

This method maps to the mlpiCore function mlpiApiGetClientCoreVersion, where you can find further documentation.

HRESULT IMlpiConnection::GetServerCoreVersion

(

[out, retval] struct Version *

versionInfo

)

This function returns the version info of the MLPI server library.

Parameters

[out]

versionInfo

Pointer to struct receiving the version info.

Returns

Return value indicating success (>=0) or error (<0).

Example C#:

try
{
  // read the version info. 
  commlpiLib.Version version = connection.GetServerCoreVersion();

  // print to console
  Console.WriteLine("Major:  " + version.major);
  Console.WriteLine("Minor:  " + version.minor);
  Console.WriteLine("Bugfix:  " + version.bugfix);
  Console.WriteLine("Patch:  " + version.patch);
  Console.WriteLine("Build:  " + version.build);
}
catch (System.Exception ex)
{
  Console.WriteLine("Error: " + ex.Message);
}

Note:

This method maps to the mlpiCore function mlpiApiGetServerCoreVersion, where you can find further documentation.

Property Documentation

VARIANT_BOOL IMlpiConnection::IsConnected

getproperty

This function returns the current state of the MLPI connection. If FALSE is returned, then the connection is either not yet established or closed due to a communication error or because Disconnect has been called. In all cases, a reconnect using Connect has to be made to make new MLPI method calls. If connection has been lost for an unknown reason, try increasing the connection timeout using Connect.

Parameters

[out]

pConnected

Returns TRUE if a connection has been established and FALSE if disconnected.

Returns

Return value indicating success (>=0) or error (<0).

Example C#:

MlpiConnection connection = new MlpiConnection();

// show connection status when not connected yet --> False
Console.WriteLine(connection.IsConnected.ToString());

// show connection status when connected --> True
connection.Connect ("192.168.0.17");
Console.WriteLine(connection.IsConnected.ToString());

// show connection status when disconnected again --> False
connection.Disconnect();
Console.WriteLine(connection.IsConnected.ToString());

Example VBA:

Dim connection As MlpiConnection
Set connection = New MlpiConnection

' show connection status when not connected yet --> False
MsgBox connection.IsConnected

' show connection status when connected --> True
connection.Connect "192.168.0.17"
MsgBox connection.IsConnected

' show connection status when disconnected again --> False
connection.Disconnect
MsgBox connection.IsConnected

Note:

This method maps to the mlpiCore function mlpiApiIsConnected, where you can find further documentation.

ISystem IMlpiConnection::System

getproperty

Property to access the System methods of the MLPI device by providing access to the ISystem interface.

Parameters

[out]

pVal

Returns the System object.

Returns

Return value indicating success (>=0) or error (<0).

IMotion IMlpiConnection::Motion

getproperty

Property to access the Motion methods of the MLPI device by providing access to the IMotion interface.

Parameters

[out]

pVal

Returns the Motion object.

Returns

Return value indicating success (>=0) or error (<0).

ILogic IMlpiConnection::Logic

getproperty

Property to access the Logic methods of the MLPI device by providing access to the ILogic interface.

Parameters

[out]

pVal

Returns the Logic object.

Returns

Return value indicating success (>=0) or error (<0).

IParameter IMlpiConnection::Parameter

getproperty

Property to access the Parameter methods of the MLPI device by providing access to the IParameter interface.

Parameters

[out]

pVal

Returns the IParameter object.

Returns

Return value indicating success (>=0) or error (<0).

IWatchdog IMlpiConnection::Watchdog

getproperty

Property to access the Watchdog methods of the MLPI device by providing access to the IWatchdog interface.

Parameters

[out]

pVal

Returns the Watchdog object.

Returns

Return value indicating success (>=0) or error (<0).

IIo IMlpiConnection::Io

getproperty

Property to access the Input/Output methods of the MLPI device by providing access to the IIo interface.

Parameters

[out]

pVal

Returns the IO object.

Returns

Return value indicating success (>=0) or error (<0).

ITrace IMlpiConnection::Trace

getproperty

Property to access the Trace methods of the MLPI device by providing access to the ITrace interface.

Parameters

[out]

pVal

Returns the Trace object.

Returns

Return value indicating success (>=0) or error (<0).

IContainer IMlpiConnection::Container

getproperty

Property to access the Container methods of the MLPI device by providing access to the IContainer interface.

Parameters

[out]

pVal

Returns the Trace object.

Returns

Return value indicating success (>=0) or error (<0).

IRobot IMlpiConnection::Robot

getproperty

Property to access the Robot methods of the MLPI device by providing access to the IRobot interface.

Parameters

[out]

pVal

Returns the Trace object.

Returns

Return value indicating success (>=0) or error (<0).

---

The documentation for this interface was generated from the following file:

• IMlpiConnection.idl