Connection control

Collaboration diagram for Connection control:

Functions
MLPIRESULT	mlpiApiConnect (const WCHAR16 *connectionIdentifier, MLPIHANDLE *connection)
MLPIRESULT	mlpiApiDisconnect (MLPIHANDLE *connection)
MLPIRESULT	mlpiApiSetDefaultTimeout (const ULONG timeout)
MLPIRESULT	mlpiApiGetDefaultTimeout (ULONG *timeout)
MLPIRESULT	mlpiApiIsConnected (const MLPIHANDLE connection, BOOL8 *isConnected)
MLPIRESULT	mlpiApiTestConnection (const MLPIHANDLE connection, const ULONG payload, const ULONG numMeasurements, MlpiConnectionInfo *info)
MLPIRESULT	mlpiApiNotifyAlive (const MLPIHANDLE connection)

Detailed Description

The following functions are used for initializing and configuring the API. This has to be done at least once and before the user application wants to use the MLPI-API.

Function Documentation

MLPIRESULT mlpiApiConnect	(	const WCHAR16 *	connectionIdentifier,
		MLPIHANDLE *	connection
	)

This function connects the user application with a specified MLC/MLP/XLC. The first argument of the connect ident string is used to specify the target device to which you want to connect. This can either be the same physical device as your application or a device that is connected via a network. In this case you have to give the IP or host name to the target. As an alternative, this address argument can be set as an option on each place within the connect ident string.

Additionally, the communication to the target can be insecured (MLPI) or secured (MLPIS). MLPI is achieved with the use of the TCP/IP protocol that allows to establish a connection with the target device and the information exchanged within this connection is unencrypted. MLPIS is achieved with the use of the TLS/SSL protocol that allows to encrypt the information exchanged. See MLPI and MLPIS for more information about these two communication protocols.

To establish an MLPIS connection the arguments 'tls' needs to be specified (as seen in the table below), if it is not given, then non secure MLPI connection is used by default. The client is not required to provide credentials (i.e. private key and certificate), however, the server must provide them. These credentials are automatically generated in targets with Firmware versions starting with version 14V18. They can also be replaced by other credentials as specified in MLPIS.

On a successful connect, the function returns a connection handle on the second argument. Use this connection handle for subsequent calls to mlpi functions.

Example using TCP/IP communication (MLPI):

MLPIHANDLE connection = 0;
MLPIRESULT result = mlpiApiConnect(L"192.168.0.42", &connection);
if (MLPI_FAILED(result)){
  printf("\nfailed to connect to MLPI with 0x%08x", (unsigned) result);
  return;
}else {
  printf("\nsuccessfully connected!");
}

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

Option	Description
user=value	Login name of user. See Permission and user management for more information about user and permission system.
password=value	Password of user. See Permission and user management for more information about user and permission system.
address=value	IP or URL path of connection.
timeout_connect=value	Timeout used for connecting in milliseconds (infinite: MLPI_INFINITE).
timeout_send=value	Timeout of MLPI client used for sending data to server (target) in milliseconds (default: 0, infinite: MLPI_INFINITE).
timeout_receive=value	Timeout of MLPI client used for receiving data from server (target) in milliseconds (default: 0, infinite: MLPI_INFINITE).
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 (default: false).
keepalive_mode_server=value	If set to 1 (default, isn't set), then the MLPI server will send a MLPI keepalive telegram after keepalive timeout, if the client does not send any request before. If set to 0, then MLPI server will not send any MLPI keepalive telegrams.
keepalive_timeout_server=value	Timeout used for sending MLPI keepalive telegram in milliseconds (default: 30000).
keepalive_probes_server=value	Number of probes for sending MLPI keepalive telegram (default: 10).
timeout_send_server=value	Timeout of MLPI server used for sending data to client in milliseconds (default: 60000, infinite: MLPI_INFINITE).
require_hash=value	If true, then only logins to servers which support hashed password logins are allowed. Server version has to be greater than 1.1.1.0 (default: false). Note It's highly recommended to use this option if your control firmware corresponds to or it newer than 13V06.
protection=value	Select your protection level using values of MlpiApiProtection to protect your connection against closing by an other connection with the assistance of call of mlpiApiCloseConnectionByUid, mlpiApiCloseConnectionsByUser or mlpiApiCloseConnectionsByUri. Note This option can be also used as an attribute of an account of the user management. See Permission and user management for more information about user and permission system. value==0 The connection is not protected and can be closed by an other connection (default). value==1 The connection is protected against closing by an other connection if the connection watchdog is active (enabled and not fired). value==2 The connection is protected against closing by an other connection completely.
tls=value	If set to 'active', then MLPI is tunneled through TLS rather than TCP, thus providing data confidentiality and integrity for the connection (default: false). It is highly recommended to change this setting to true if possible.

Example using TCP/IP communication (MLPI):

MLPIHANDLE connection = 0;
MLPIRESULT result = mlpiApiConnect(L"192.168.0.42 -timeout_connect=2000 -timeout_send=5000 -timeout_receive=5000 -user=guest -password=guest -auto_reconnect=true", &connection);
if (MLPI_FAILED(result)){
  printf("\nfailed to connect to MLPI with 0x%08x", (unsigned)result);
  return;
}else{
  printf("\nsuccessfully connected!");
}

Example using TLS/SSL communication (MLPIS):

MLPIHANDLE connection = 0;
MLPIRESULT result = mlpiApiConnect(L"192.168.0.42 -timeout_connect=2000 -timeout_send=5000 -timeout_receive=5000 -user=guest -password=guest -auto_reconnect=true 
-tls=active", &connection);
if (MLPI_FAILED(result)){
  printf("\nfailed to connect to MLPI with 0x%08x", (unsigned)result);
  return;
}else{
  printf("\nsuccessfully connected!");
}

A timeout value of 0 means that the timeout value is to be chosen automatically by the operating system. If no timeout is specified here, the global default value as set by the function mlpiApiSetDefaultTimeout is used. This means that any option given here will override the value as set by mlpiApiSetDefaultTimeout. In most cases it is not recommended to override the timeout values. Especially the send and receive timeouts should stay at their default values of 0.

The second argument is handy if you want to establish more than one connection using the MLPI. For example, if you want to connect to two or more devices at the same time. Or if you want to have more than a single connection to the same device. As already noted, you have to pass a pointer to a MLPIHANDLE variable as second argument to this function. If the function succeeds, it will return a handle which identifies your connection. Use this handle as first argument to all existing MLPI functions. This way, the MLPI function knows on which connection and therefore on which target to execute the MLPI function.

If no request telegram of the MLPI client will be received by the MLPI server, by default, the MLPI server will send on any 'keepalive_timeout_server' milliseconds timeout an empty MLPI keepalive telegram. This is done to check if the client machine is still reachable or if the connection can be closed and freed again. The server will repeat this keepalive telegram for 'keepalive_probes_server' times. After this time ('keepalive_timeout_server' * 'keepalive_probes_server'), the MLPI server waits 'timeout_send_server' milliseconds until the connection is closed finally.

Overall timeout until close of connection:

t(close) = ( t(keepalive_timeout_server) * n(keepalive_probes_server) ) + t(timeout_send_server)

Note

The server cannot detect whether the client application is still running. It can only be checked if the telegrams reached the client machine and the socket is still available. To setup a durable connection, it can also be helpful to implement the function mlpiApiNotifyAlive.

Example using TCP/IP (MLPI) and TLS/SSL communications (MLPIS):

MLPIHANDLE handle1=0;                                     // this is the handle of the first connection
MLPIHANDLE handle2=0;                                     // this is the handle of the second connection
mlpiApiConnect(L"192.168.0.17", &handle1);
mlpiApiConnect(L"192.168.0.42 -tls=active", &handle2);

WCHAR szText1[128];
WCHAR szText2[128];
mlpiSystemGetName(handle1, szText1, _countof(szText1));   // now using the handle to identify the first target
mlpiSystemGetName(handle2, szText2, _countof(szText2));   // now using the handle to identify the second target
printf("\nName1: %s", W2A16(szText1));
printf("\nName2: %s", W2A16(szText2));

mlpiApiDisconnect(&handle1);
mlpiApiDisconnect(&handle2);

About the return value.

A few words on the return values of the mlpiApiConnect() function.

Use case	Return value
Successful connect to a MLPI device.	Positive value.
The given connection ident string doesn't contain an address.	MLPI_E_INVALIDARG
No MLPI device found at the given address, e.g. invalid IP address.	MLPI_E_CONNECTFAILED
A connection could not be established in the given timeout time as provided by mlpiApiSetDefaultTimeout or "-timeout_connect=xxxx".	MLPI_E_TIMEOUT
MLPI device found, but connection refused because of incompatible version of client library and mlpi device.	MLPI_E_VERSION
MLPI device found, but connection refused because of missing privileges or invalid user/password settings.	MLPI_E_PERMISSION
MLPI device found, but connection refused because there are already too much clients or user connected.	MLPI_E_LIMIT_MAX
A connection could not be established because there was an error with the provided private key.	MLPI_E_INVALID_PRIVATEKEY_FILE
A connection could not be established because there was an error with the provided certificate.	MLPI_E_INVALID_CERTIFICATE_FILE
A connection could not be established because the private key and certificate do not match one another.	MLPI_E_KEYPAIR_MISSMATCH
A connection could not be established because there was an error with the TLS handshake.	MLPI_E_TLS_HANDSHAKE_FAILED

A call to any other MLPI function prior to calling mlpiApiConnect will return MLPI_E_NOCONNECTION. If a send or receive timeout is set and a MLPI function call times out due to these settings, then this MLPI function call will return MLPI_E_TIMEOUT. The connection is then inconsistent and will therefore be closed automatically. Any following MLPI function call will then return with MLPI_E_NOCONNECTION. This means that after a timeout, a new connection has to be established using mlpiApiConnect unless you made the connect with optional argument auto_reconnect=true (see above). In this case, the MLPI tries to reconnect in the context of each new MLPI function call.

Parameters

[in]	connectionIdentifier	The connect ident string identifying the device. Use MLPI_LOCALHOST to connect to the system running on the same host device. Use an IP address to connect over Ethernet to another device. This string may also contain an additional argument list (options).
[out]	connection	Returns handle of connection, if successful. Has to be canceled by calling mlpiApiDisconnect. Calling mlpiApiConnect without corresponding mlpiApiDisconnect on application termination will result in a memory leak!

Returns

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

MLPIRESULT mlpiApiDisconnect

(

MLPIHANDLE *

connection

)

This function disconnects the user application from the target.

The connection identified by the handle is closed and destroyed. It is then not allowed to use the handle in any subsequent MLPI call.

Parameters

[in]

connection

Handle for multiple connections.

Returns

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

Example using TCP/IP communication (MLPI):

MLPIHANDLE connection = 0;
MLPIRESULT result = mlpiApiConnect(L"192.168.0.10:5300 -timeout_connect=2000 -timeout_send=5000 -timeout_receive=5000 -user=guest -pass=guest -auto_reconnect=true", &connection);
if (MLPI_FAILED(result)){
  printf("\nfailed to connect to MLPI with 0x%08x", (unsigned)result);
  return;
}else{
  printf("\nsuccessfully connected!");
}

// insert some mlpi calls here...

result = mlpiApiDisconnect(&connection);
if (MLPI_FAILED(result)){
  printf("\nerror on disconnect from MLPI with 0x%08x", (unsigned)result);
  return;
}else{
  printf("\nsuccessfully disconnected!");
}

MLPIRESULT mlpiApiSetDefaultTimeout

(

const ULONG

timeout

)

This function sets the default timeout for remote procedure calls done by the API. The timeout is used for connecting, sending and receiving data. During the debugging of your application, you might want to set this value to MLPI_INFINITE.

Note

• This value has to be set BEFORE connecting to a target.
• This value can be overridden by options which are given as an argument list to mlpiApiConnect.

Parameters

[in]

timeout

This is the timeout in milliseconds when doing remote procedure calls via the MLPI-API.

Returns

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

MLPIRESULT mlpiApiGetDefaultTimeout

(

ULONG *

timeout

)

This function reads the default timeout for remote procedure calls done by the API. This might not be the value that is set for a currently active connection.

Parameters

[out]

timeout

This is the timeout in milliseconds when doing remote procedure calls via the MLPI-API.

Returns

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

MLPIRESULT mlpiApiIsConnected	(	const MLPIHANDLE	connection,
		BOOL8 *	isConnected
	)

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

Parameters

[in]	connection	Handle for multiple connections.
[out]	isConnected	Returns TRUE if connection is established and FALSE if disconnected.

Returns

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

Example:

BOOL8 isConnected = FALSE;
MLPIRESULT result = mlpiApiIsConnected(connection, &isConnected);

if (MLPI_SUCCEEDED(result) && isConnected) {
  printf("\nMLPI connection is established!");
}

MLPIRESULT mlpiApiTestConnection	(	const MLPIHANDLE	connection,
		const ULONG	payload,
		const ULONG	numMeasurements,
		MlpiConnectionInfo *	info
	)

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]	connection	Handle for multiple connections.
[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]	info	Pointer to structure which receives the calculated timing values.

Returns

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

Example:

ULONG payload = 100;              // 100 byte transfer data
ULONG numMeasurements = 1000;     // 1000 iterations for statistics
MlpiConnectionInfo connectionInfo = {0};

// do measurements
MLPIRESULT result = mlpiApiTestConnection(connection, payload, numMeasurements, &connectionInfo);
if (MLPI_FAILED(result)){
  printf("mlpiApiTestConnection failed with 0x%08x", (unsigned)result);
  return;
}
// print results
printf(L"\nTimings in milliseconds:");
printf(L"\nPayload: \t\t%7d", payload);
printf(L"\nAverage: \t\t%15.6lf", connectionInfo.average*0.001);
printf(L"\nMinimum: \t\t%15.6lf", connectionInfo.minimum*0.001);
printf(L"\nMaximum: \t\t%15.6lf", connectionInfo.maximum*0.001);
printf(L"\nVariance: \t\t%15.6lf", connectionInfo.variance*0.001*0.001);
printf(L"\nStandard Deviation: \t\t%15.6lf", connectionInfo.standardDeviation*0.001);

MLPIRESULT mlpiApiNotifyAlive

(

const MLPIHANDLE

connection

)

This function notifies the MLPI server that the client is still alive. You may need this function if you use the keepalive mechanism of the MLPI server (mlpiApiConnect).

Note

By using of keepalive options, the server will send keepalive telegrams to the client until the server recognizes a zombie connection. This is because the keepalive telegrams of the MLPI server also fills the receive buffer of the client until the client sends any new request or until the client buffer is full and causes an error. To prevent this error and empty the client buffer from keepalive telegrams, use this or any other function.

Parameters

[in]

connection

Handle for multiple connections.

Returns

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

Example:

// notify MLPI server that the client is still alive
MLPIRESULT result = mlpiApiNotifyAlive(connection);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", (unsigned) result);
  return result;
}