Collaboration diagram for Utility functions:

Functions
MLPIRESULT	mlpiApiDelay (const MLPIHANDLE connection, const ULONG delayMilliseconds)

MLPIRESULT	mlpiApiGetClientCoreVersion (MlpiVersion *versionInfo)

MLPIRESULT	mlpiApiGetServerCoreVersion (const MLPIHANDLE connection, MlpiVersion *versionInfo)

MLPIRESULT	mlpiApiSetNameOfConnection (const MLPIHANDLE connection, const WCHAR16 *name)

MLPIRESULT	mlpiApiSetLabelOfConnection (const MLPIHANDLE connection, const WCHAR16 *label)

MLPIRESULT	mlpiApiGetOwnConnectionDescription (const MLPIHANDLE connection, MlpiConnectionDescription *description)

MLPIRESULT	mlpiApiGetAllConnectionDescription (const MLPIHANDLE connection, MlpiConnectionDescription description, const ULONG numElements, ULONG numElementsRet)

MLPIRESULT	mlpiApiCloseConnectionByUid (const MLPIHANDLE connection, const ULLONG uid)

MLPIRESULT	mlpiApiCloseConnectionsByUser (const MLPIHANDLE connection, const WCHAR16 *user)

MLPIRESULT	mlpiApiCloseConnectionsByUri (const MLPIHANDLE connection, const WCHAR16 *uri)

MLPIRESULT	mlpiApiUserAccountControlReload (const MLPIHANDLE connection)

MLPIRESULT	mlpiApiUserAccountControlLoadAccounts (const MLPIHANDLE connection, const WCHAR16 *path)

MLPIRESULT	mlpiApiUserAccountControlUnloadAccounts (const MLPIHANDLE connection, const WCHAR16 *path)

MLPIRESULT	mlpiApiGetOwnPermissions (const MLPIHANDLE connection, WCHAR16 permissions, const ULONG numElements, ULONG numElementsRet)

MLPIRESULT	mlpiApiGetAccounts (const MLPIHANDLE connection, WCHAR16 accounts, const ULONG numElements, ULONG numElementsRet)

MLPIRESULT	mlpiApiGetAccountPermissions (const MLPIHANDLE connection, const WCHAR16 account, WCHAR16 permissions, const ULONG numElements, ULONG *numElementsRet)

MLPIRESULT	mlpiApiGetLibrarySupport (const MLPIHANDLE connection, MlpiLibrary library, const ULONG numElements, ULONG numElementsRet)

Detailed Description

Contains various functions which are handy for MLPI connection testing and information.

Function Documentation

MLPIRESULT mlpiApiDelay	(	const MLPIHANDLE	connection,
		const ULONG	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 device.

Parameters

[in]	connection	Handle for multiple connections.
[in]	delayMilliseconds	Delay in milliseconds to block.

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

MLPIRESULT mlpiApiGetClientCoreVersion ( MlpiVersion * versionInfo )

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

Parameters

[out] versionInfo Pointer to struct receiving the version info.

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

Example:: 1 MlpiVersion versionInfo;
2 memset(&versionInfo, 0, sizeof(versionInfo));
3 MLPIRESULT result = mlpiApiGetClientCoreVersion(&versionInfo);
4
5 if (MLPI_FAILED(result)) {
6 printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
7 } else {
8 printf("\nVersion (Major, Minor, Bugfix, Patch): %d.%d.%d.%d Build: %d"
9 , versionInfo.major
10 , versionInfo.minor
11 , versionInfo.bugfix
12 , versionInfo.patch
13 , versionInfo.build);
14 }

MLPIRESULT mlpiApiGetServerCoreVersion	(	const MLPIHANDLE	connection,
		MlpiVersion *	versionInfo
	)

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

Parameters

[in]	connection	Handle for multiple connections.
[out]	versionInfo	Pointer to struct receiving the version info.

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

Example:: 1 MlpiVersion versionInfo;
2 memset(&versionInfo, 0, sizeof(versionInfo));
3 MLPIRESULT result = mlpiApiGetServerCoreVersion(connection, &versionInfo);
4
5 if (MLPI_FAILED(result)) {
6 printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
7 } else {
8 printf("\nVersion (Major, Minor, Bugfix, Patch): %d.%d.%d.%d Build: %d"
9 , versionInfo.major
10 , versionInfo.minor
11 , versionInfo.bugfix
12 , versionInfo.patch
13 , versionInfo.build);
14 }

MLPIRESULT mlpiApiSetNameOfConnection	(	const MLPIHANDLE	connection,
		const WCHAR16 *	name
	)

Using this function, you can assign a short descriptive name to your connection. It is not necessary to give your connection a name, but the name might be useful for debugging and maintaining your connections.

Parameters

[in]	connection	Handle for multiple connections.
[in]	name	User-defined name of connection.

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

Example:: 1 // let's call our connection 'The Hitchhiker's Guide to the Galaxy.'
2 MLPIRESULT result = mlpiApiSetNameOfConnection(connection, L"The Hitchhiker's Guide to the Galaxy.");
3 if (MLPI_FAILED(result)) {
4 printf("\ncall of MLPI function failed with 0x%08x!", (unsigned) result);
5 return result;
6 }

MLPIRESULT mlpiApiSetLabelOfConnection	(	const MLPIHANDLE	connection,
		const WCHAR16 *	label
	)

Using this function, you can assign a long descriptive label to your connection. It is not necessary to set the connection label, but the label might be useful for debugging and maintaining your connections.

Parameters

[in]	connection	Handle for multiple connections.
[in]	label	User-defined label of connection.

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

Example:: 1 // let's label our connection with 'The answer to the Ultimate Question of Life, the Universe, and Everything is... 42.'
2 MLPIRESULT result = mlpiApiSetLabelOfConnection(connection, L"The answer to the Ultimate Question of Life, the Universe, and Everything is... 42.");
3 if (MLPI_FAILED(result)) {
4 printf("\ncall of MLPI function failed with 0x%08x!", (unsigned) result);
5 return result;
6 }

MLPIRESULT mlpiApiGetOwnConnectionDescription	(	const MLPIHANDLE	connection,
		MlpiConnectionDescription *	description
	)

This function will return information about the own connection.

Parameters

[in]	connection	Handle for multiple connections.
[out]	description	Pointer to struct receiving the connection descriptions.

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

Example:: 1 MlpiConnectionDescription description;
2 memset(&description, 0, sizeof(description));
3
4 // get information about all connections
5 MLPIRESULT result = mlpiApiGetOwnConnectionDescription(connection, description);
6 if(MLPI_SUCCEEDED(result)) {
7 printf("\n\n* %d", i);
8 printf("\n\tuid: 0x%08X.%08X", (ULONG) (description.uid>>32), (ULONG) description.uid);
9 printf("\n\tuser: %s", W2A16(description.user));
10 printf("\n\turi: %s", description.uri);
11 printf("\n\tname: %s", W2A16(description.name));
12 printf("\n\tlabel: %s", W2A16(description.label));
13 printf("\n\tdate an time: %04u-%02u-%02u %02u-%02u-%02u (UTC)",
14 description.dateTime.year, description.dateTime.month, description.dateTime.day,
15 description.dateTime.hour, description.dateTime.minute, description.dateTime.second);
16 printf("\n\trequests: %d", description.requestCounter);
17 printf("\n\tlast request: %d", description.lastRequest);
18 printf("\n\tprotection: %d", description.protection);
19 printf("\n\twatchdog: %s", (description.watchdog==1) ? "TRUE" : "FALSE");
20 }
21 else {
22 printf("\ncall of MLPI function failed with 0x%08x!", (unsigned) result);
23 return result;
24 }

MLPIRESULT mlpiApiGetAllConnectionDescription	(	const MLPIHANDLE	connection,
		MlpiConnectionDescription *	description,
		const ULONG	numElements,
		ULONG *	numElementsRet
	)

This function will return information about all established connections of the device.

Parameters

[in]	connection	Handle for multiple connections.
[out]	description	Pointer to struct receiving the connection descriptions.
[in]	numElements	Number of MlpiConnectionDescription elements available in 'description' to read.
[out]	numElementsRet	Number of elements used.

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

Example:: 1 ULONG numElementsRet = 0;
2 MlpiConnectionDescription description[MLPI_API_MAX_NUMBER_OF_CONNECTIONS];
3 memset(description, 0, sizeof(description));
4
5 // get information about all connections
6 MLPIRESULT result = mlpiApiGetAllConnectionDescription(connection, description, MLPI_API_MAX_NUMBER_OF_CONNECTIONS, &numElementsRet);
7 if(MLPI_SUCCEEDED(result)) {
8 for(ULONG i=0; i<numElementsRet; i++) {
9 printf("\n\n* %d", i);
10 printf("\n\tuid: 0x%08X.%08X", (ULONG) (description[i].uid>>32), (ULONG) description[i].uid);
11 printf("\n\tuser: %s", W2A16(description[i].user));
12 printf("\n\turi: %s", description[i].uri);
13 printf("\n\tname: %s", W2A16(description[i].name));
14 printf("\n\tlabel: %s", W2A16(description[i].label));
15 printf("\n\tdate an time: %04u-%02u-%02u %02u-%02u-%02u (UTC)",
16 description[i].dateTime.year, description[i].dateTime.month, description[i].dateTime.day,
17 description[i].dateTime.hour, description[i].dateTime.minute, description[i].dateTime.second);
18 printf("\n\trequests: %d", description[i].requestCounter);
19 printf("\n\tlast request: %d", description[i].lastRequest);
20 printf("\n\tprotection: %d", description[i].protection);
21 printf("\n\twatchdog: %s", (description[i].watchdog==1) ? "TRUE" : "FALSE");
22 }
23 }
24 else {
25 printf("\ncall of MLPI function failed with 0x%08x!", (unsigned) result);
26 return result;
27 }

MLPIRESULT mlpiApiCloseConnectionByUid	(	const MLPIHANDLE	connection,
		const ULLONG	uid
	)

This function closes a connection selected by the unique identifier (uid) of a connection. You can determine the uid by using the function mlpiApiGetOwnConnectionDescription.

Note: A connection cannot be closed if it runs in a protected mode (see MlpiApiProtection). In this case, the function will return the error MLPI_E_RD_WR_PROTECTION.

Parameters

[in]	connection	Handle for multiple connections.
[in]	uid	Unique identifier of connection.

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

Example:: 1 // close the connection with the uid 0x0000002A.12345678
2 MLPIRESULT result = mlpiApiCloseConnectionByUid(connection, 0x0000002A.12345678);
3 if (MLPI_FAILED(result)) {
4 printf("\ncall of MLPI function failed with 0x%08x!", (unsigned) result);
5 return result;
6 }

MLPIRESULT mlpiApiCloseConnectionsByUser	(	const MLPIHANDLE	connection,
		const WCHAR16 *	user
	)

This function closes one or multiple connections selected by the user.

Note: A connection cannot be closed if it runs in a protected mode (see MlpiApiProtection). In this case, the function will return the error MLPI_E_RD_WR_PROTECTION.

Parameters

[in]	connection	Handle for multiple connections.
[in]	user	Login user name of connection.

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

Example:: 1 // close all connections of the user 'Batman'
2 MLPIRESULT result = mlpiApiCloseConnectionsByUser(connection, L"Batman");
3 if (MLPI_FAILED(result)) {
4 printf("\ncall of MLPI function failed with 0x%08x!", (unsigned) result);
5 return result;
6 }

MLPIRESULT mlpiApiCloseConnectionsByUri	(	const MLPIHANDLE	connection,
		const WCHAR16 *	uri
	)

This function closes one or multiple connections selected by a combination of the uniform resource identifier (uri) and the placeholder '*'.

Note: A connection cannot be closed if it runs in a protected mode (see MlpiApiProtection). In this case, the function will return the error MLPI_E_RD_WR_PROTECTION.

Parameters

[in]	connection	Handle for multiple connections.
[in]	uri	URI of connection (e.g. "mlpi.tcp://'IP-address':'port'").

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

Example:: 1 // close all connections of the device with the uri 'mlpi.tcp://192.168.0.42*'
2 MLPIRESULT result = mlpiApiCloseConnectionsByUri(connection, L"mlpi.tcp://192.168.0.42*");
3 if (MLPI_FAILED(result)) {
4 printf("\ncall of MLPI function failed with 0x%08x!", (unsigned) result);
5 return result;
6 }

MLPIRESULT mlpiApiUserAccountControlReload ( const MLPIHANDLE connection )

This function provides the reloading of all currently loaded account manifests know as 'accounts.xml'.

Note: The permissions of an established connection will not be influenced from new accounts settings.

Attention: A fail of reloading of the default account manifests maybe requires a reboot of the control because another new connection cannot be established furthermore.

Parameters

[in] connection Handle for multiple connections.

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

Example:: 1 // reload accounts of default account manifests and additional account manifests
2 MLPIRESULT result = mlpiApiUserAccountControlReload(connection);
3 if (MLPI_FAILED(result)) {
4 printf("\ncall of MLPI function failed with 0x%08x!", (unsigned) result);
5 return result;
6 }

MLPIRESULT mlpiApiUserAccountControlLoadAccounts	(	const MLPIHANDLE	connection,
		const WCHAR16 *	path
	)

Note: This function is deprecated since server version 1.19.0. Do not use this function in combination with the AccessControlLib!

This function provides the loading of the accounts of an additional account manifest.

Note: It's recommended, but not required to name the additional account manifest 'accounts.xml'.

Parameters

[in]	connection	Handle for multiple connections.
[in]	path	Path to the additional account manifest.

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

Example:: 1 // load accounts of an additional account manifest
2 WCHAR16 path[256] = L"";
3 WCHAR16 file[] = L"bundles/com.boschrexroth.mlpi.test42/accounts.xml";
4 if ( MLPI_SUCCEEDED(mlpiSystemGetSpecialPath(MLPI_PATH_OEM, path, _countof(path))) )
5 {
6 wcscat(path, file);
7 MLPIRESULT result = mlpiApiUserAccountControlLoadAccounts(connection, path);
8 if (MLPI_FAILED(result)) {
9 printf("\ncall of MLPI function failed with 0x%08x!", (unsigned) result);
10 return result;
11 }
12 }

MLPIRESULT mlpiApiUserAccountControlUnloadAccounts	(	const MLPIHANDLE	connection,
		const WCHAR16 *	path
	)

Note: This function is deprecated since server version 1.19.0. Do not use this function in combination with the AccessControlLib!

This function provides the unloading of the accounts of an additional account manifest.

Note: The permissions of an established connection will not be influenced from new accounts settings.

Parameters

[in]	connection	Handle for multiple connections.
[in]	path	Path to the additional account manifest.

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

Example:: 1 // unload accounts of an additional account manifest
2 WCHAR16 path[256] = L"";
3 WCHAR16 file[] = L"bundles/com.boschrexroth.mlpi.test42/accounts.xml";
4 if ( MLPI_SUCCEEDED(mlpiSystemGetSpecialPath(MLPI_PATH_OEM, path, _countof(path))) )
5 {
6 wcscat16(path, file);
7 MLPIRESULT result = mlpiApiUserAccountControlUnloadAccounts(connection, path);
8 if (MLPI_FAILED(result)) {
9 printf("\ncall of MLPI function failed with 0x%08x!", (unsigned) result);
10 return result;
11 }
12 }

MLPIRESULT mlpiApiGetOwnPermissions	(	const MLPIHANDLE	connection,
		WCHAR16 *	permissions,
		const ULONG	numElements,
		ULONG *	numElementsRet
	)

This function provides the reading of own permissions based on account manifest 'accounts.xml'.

Note: In case the buffer is too short, the function will still return the required number of WCHAR16 elements by 'numElementsRet'.

Parameters

[in]	connection	Handle for multiple connections.
[out]	permissions	String where the permissions will be stored.
[in]	numElements	Number of WCHAR16 elements available in 'permissions' to read.
[out]	numElementsRet	Number of WCHAR16 elements in complete 'permissions'.

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

Example:: 1 // read own permissions
2 ULONG numElementsRet = 0;
3 WCHAR16 permissions[4096] = L"";
4
5 MLPIRESULT result = mlpiApiGetOwnPermissions(connection, permissions, _countof(permissions), &numElementsRet);
6 if (MLPI_FAILED(result)) {
7 printf("\ncall of MLPI function failed with 0x%08x!", (unsigned) result);
8 return result;
9 }
10 else
11 {
12 ULONG idx = 0;
13 CHAR permission[128] = "";
14 WCHAR16 *curr = permissions, *nxt = permissions;
15 while (true)
16 {
17 // find separator between two permissions or end of string
18 while ( (*nxt!=NULL) && (*nxt!=';') )
19 nxt++;
20 if(curr==nxt)
21 break;
22 // separate current permission string from next permission string
23 if(*nxt!=0)
24 *nxt++=0;
25 // convert and print permission string
26 wcstombs16(permission, curr, wcslen16(curr)+1);
27 printf("\n%d:\t%s", idx++, permission);
28 // go to next permission string
29 curr = nxt;
30 }
31 }

Example:: 1 #include "mlpiApiHelper.h"
2
3 ULONG numElementsRet = 0;
4 WCHAR16 permissions[4096] = L"";
5
6 MLPIRESULT result = mlpiApiGetOwnPermissions(connection, permissions, _countof(permissions), &numElementsRet);
7 if (MLPI_FAILED(result)) {
8 printf("\ncall of MLPI function failed with 0x%08x!", (unsigned) result);
9 return result;
10 }
11 else
12 {
13 WCHAR16 requiredPermission[] = L"MLPI_APILIB_PERMISSION_CONNECTION_CLOSE";
14
15 MlpiApiPermissionEvaluation evalPermission(permissions);
16
17 if (evalPermission.hasPermission(requiredPermission))
18 log(L"\nThe logged in user has the permission '%s'.", requiredPermission);
19 else
20 warning(L"\nThe logged in user hasn't the permission '%s'.", requiredPermission);
21 }

MLPIRESULT mlpiApiGetAccounts	(	const MLPIHANDLE	connection,
		WCHAR16 *	accounts,
		const ULONG	numElements,
		ULONG *	numElementsRet
	)

Note: This function is deprecated since server version 1.19.0. Use the function mlpiAccessControlGetAllUserInfos from the AccessControlLib instead!

This function provides the reading of all available accounts based on account manifest 'accounts.xml'.

Note: An account with empty name will be replaced by the surrogate string MLPI_ACCOUNT_EMPTY_NAME but this surrogate string cannot used as login name!

Note: In case the buffer is too short, the function will still return the required number of WCHAR16: elements by 'numElementsRet'.

Parameters

[in]	connection	Handle for multiple connections.
[out]	accounts	String where the accounts will be stored.
[in]	numElements	Number of WCHAR16 elements available in 'accounts' to read.
[out]	numElementsRet	Number of WCHAR16 elements in complete 'accounts'.

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

Example:: 1 // read all available accounts
2 ULONG numElementsRet = 0;
3 WCHAR16 accounts[1024] = L"";
4
5 MLPIRESULT result = mlpiApiGetAccounts(connection, accounts, _countof(accounts), &numElementsRet);
6 if (MLPI_FAILED(result)) {
7 printf("\ncall of MLPI function failed with 0x%08x!", (unsigned) result);
8 return result;
9 }
10 else
11 {
12 ULONG idx = 0;
13 CHAR account[128] = "";
14 WCHAR16 *curr = accounts, *nxt = accounts;
15 while (true)
16 {
17 // find separator between two accounts or end of string
18 while ( (*nxt!=NULL) && (*nxt!=';') )
19 nxt++;
20 if(curr==nxt)
21 break;
22 // separate current account string from next account string
23 if (*nxt!=0)
24 *nxt++=0;
25 // remove surrogate string of account with empty name
26 if(wcscmp16(curr, MLPI_ACCOUNT_EMPTY_NAME)==0)
27 *curr = 0;
28 // convert account string
29 wcstombs16(account, curr, wcslen16(curr)+1);
30 printf("\n%d:\t%s", idx++, account);
31 // go to next account string
32 curr = nxt;
33 }
34 }

MLPIRESULT mlpiApiGetAccountPermissions	(	const MLPIHANDLE	connection,
		const WCHAR16 *	account,
		WCHAR16 *	permissions,
		const ULONG	numElements,
		ULONG *	numElementsRet
	)

This function provides the reading of the permissions of an account based on account manifest 'accounts.xml'.

Note: In case the buffer is too short, the function will still return the required number of WCHAR16 elements by 'numElementsRet'.

Parameters

[in]	connection	Handle for multiple connections.
[in]	account	String that identifies the account for which permissions were read. Set to NULL to get your own permissions.
[out]	permissions	String where the permissions will be stored.
[in]	numElements	Number of WCHAR16 elements available in 'permissions' to read.
[out]	numElementsRet	Number of WCHAR16 elements in complete 'permissions'.

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

Example:: 1 // read permissions of account 'administrator'
2 ULONG numElementsRet = 0;
3 WCHAR16 permissions[4096] = L"";
4
5 MLPIRESULT result = mlpiApiGetAccountPermissions(connection, L"administrator", permissions, _countof(permissions), &numElementsRet);
6 if (MLPI_FAILED(result)) {
7 printf("\ncall of MLPI function failed with 0x%08x!", (unsigned) result);
8 return result;
9 }
10 else
11 {
12 ULONG idx = 0;
13 CHAR permission[128] = "";
14 WCHAR16 *curr = permissions, *nxt = permissions;
15 while (true)
16 {
17 // find separator between two permissions or end of string
18 while ( (*nxt!=NULL) && (*nxt!=';') )
19 nxt++;
20 if(curr==nxt)
21 break;
22 // separate current permission string from next permission string
23 if (*nxt!=0)
24 *nxt++=0;
25 // convert and print permission string
26 wcstombs16(permission, curr, wcslen16(curr)+1);
27 printf("\n%d:\t%s", idx++, permission);
28 // go to next permission string
29 curr = nxt;
30 }
31 }

MLPIRESULT mlpiApiGetLibrarySupport	(	const MLPIHANDLE	connection,
		MlpiLibrary *	library,
		const ULONG	numElements,
		ULONG *	numElementsRet
	)

This function provides names and IDs of supported libraries.

Parameters

[in]	connection	Handle for multiple connections.
[out]	library	Struct where names and IDs of supported libraries will be stored.
[in]	numElements	Number of MlpiLibrary elements available in 'library' to read.
[out]	numElementsRet	Number of MlpiLibrary elements in complete 'library'.

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

Example:: 1 ULONG numElementsRet = 0;
2 MlpiLibrary library[32];
3 memset(library, 0, sizeof(library));
4
5 // Get names and IDs of supported libraries.
6 MLPIRESULT result = mlpiApiGetLibrarySupport(connection, library, _countof(library), &numElementsRet);
7 if(MLPI_SUCCEEDED(result)) {
8 for(ULONG i=0; i<numElementsRet; i++) {
9 printf("\n\n* %d", i);
10 printf("\n\tname: %s", W2A16(library[i].name));
11 printf("\n\tid: %08X", library[i].id);
12 }
13 }
14 else {
15 printf("\ncall of MLPI function failed with 0x%08x!", (unsigned) result);
16 return result;
17 }

Functions

Detailed Description

Function Documentation