Auxiliary function

Collaboration diagram for Auxiliary function:

Functions
MLPIRESULT	mlpiContainerSetName (const MLPIHANDLE connection, const MlpiContainerHandle handle, const WCHAR16 *name)
MLPIRESULT	mlpiContainerGetName (const MLPIHANDLE connection, const MlpiContainerHandle handle, WCHAR16 *name, const ULONG numElements)
MLPIRESULT	mlpiContainerGetInformation (const MLPIHANDLE connection, const MlpiContainerHandle handle, MlpiContainerInformation *info)
MLPIRESULT	mlpiContainerGetTagList (const MLPIHANDLE connection, const MlpiContainerHandle handle, WCHAR16 *tagList, const ULONG numElements)
MLPIRESULT	mlpiContainerGetItemInformation (const MLPIHANDLE connection, const MlpiContainerHandle handle, MlpiContainerItemInformation *info, const ULONG numElements, ULONG *numElementsRet)
MLPIRESULT	mlpiContainerGetSingleItemInformation (const MLPIHANDLE connection, const MlpiContainerHandle handle, const ULONG index, WCHAR16 *tag, const ULONG numElements, MlpiContainerItemInformation *info)
MLPIRESULT	mlpiContainerGetNumberOfContainer (const MLPIHANDLE connection, ULONG *number)
MLPIRESULT	mlpiContainerGetHandlesOfContainer (const MLPIHANDLE connection, MlpiContainerHandle *handles, const ULONG numElements, ULONG *numElementsRet)

Detailed Description

Contains additional functions for getting more detailed information about the properties and structure of a container.

Attention

The addresses of the variables of the container content might change on every download, reset origin or online change of the PLC application, so you have to stop and destroy each regarding container before you load or change the PLC application!

These functions are not needed for simple reading and writing using containers. Use them only if you want to dive deeper into the container system of the MLPI.

Function Documentation

MLPIRESULT mlpiContainerSetName	(	const MLPIHANDLE	connection,
		const MlpiContainerHandle	handle,
		const WCHAR16 *	name
	)

Using this function, you can assign a descriptive name to your container. The name can be any string. Duplicates are allowed. It is not necessary to give your container a name, but the name is used on diagnosis messages and might be useful for debugging and maintaining your application.

Parameters

[in]	connection	Handle for multiple connections.
[in]	handle	Handle of the container. Use mlpiContainerCreate to create a container.
[in]	name	String containing a name for the container. Maximum length is defined by MLPI_CONTAINER_NAME_MAX_LENGTH.

Returns

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

Example:

// let's call our container 'Batman'
MLPIRESULT result = mlpiContainerSetName(connection, hContainer, L"Batman");
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
  return result;
}

MLPIRESULT mlpiContainerGetName	(	const MLPIHANDLE	connection,
		const MlpiContainerHandle	handle,
		WCHAR16 *	name,
		const ULONG	numElements
	)

Using this function, you can read out the name of your container. The name can be any string with a maximum size of MLPI_CONTAINER_NAME_MAX_LENGTH. Use the function mlpiContainerSetName to set the name.

Parameters

[in]	connection	Handle for multiple connections.
[in]	handle	Handle of the container. Use mlpiContainerCreate to create a container.
[out]	name	String where the container name will be stored.
[in]	numElements	Number of WCHAR16 elements in 'name' available to write.

Returns

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

Example:

WCHAR16 name[MLPI_CONTAINER_NAME_MAX_LENGTH+1] = {'\0'};
MLPIRESULT result = mlpiContainerGetName(connection, hContainer, name, _countof(name));
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
  return result;
}

printf("\nName of container: %s", W2A16(name));

MLPIRESULT mlpiContainerGetInformation	(	const MLPIHANDLE	connection,
		const MlpiContainerHandle	handle,
		MlpiContainerInformation *	info
	)

Use this function to read various pieces of information about your container. This includes time of creation, size, number of items, and type (read/write). You have to pass the container handle.

Parameters

[in]	connection	Handle for multiple connections.
[in]	handle	Handle of the container. Use mlpiContainerCreate to create a container.
[out]	info	Pointer to struct which will receive the container information.

Returns

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

Example:

// read container information
MlpiContainerInformation info;
memset(&info, 0, sizeof(info));

MLPIRESULT result = mlpiContainerGetInformation(connection, hContainer, &info);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
  return result;
}

// print container information
printf("\nname: %s", W2A16(info.name));
printf("\nnumItems: %d", info.numItems);
printf("\ndataSize: %d", info.dataSize);
printf("\nnumElementsTagList: %d", info.numElementsTagList);
printf("\naccessFlag: %d", info.accessFlag);
printf("\ndateTime: %04d/%02d/%02d %02d:%02d:%02d.%04d",
  info.dateTime.year,
  info.dateTime.month,
  info.dateTime.day,
  info.dateTime.hour,
  info.dateTime.minute,
  info.dateTime.second,
  info.dateTime.milliSecond);

MLPIRESULT mlpiContainerGetTagList	(	const MLPIHANDLE	connection,
		const MlpiContainerHandle	handle,
		WCHAR16 *	tagList,
		const ULONG	numElements
	)

This function returns the tag list of a container. This is the same tagList that was used to create the container with the function mlpiContainerCreate.

Parameters

[in]	connection	Handle for multiple connections.
[in]	handle	Handle of the container. Use mlpiContainerCreate to create a container.
[out]	tagList	String where the tag list will be stored.
[in]	numElements	Number of WCHAR16 elements in 'name' available to write.

Returns

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

Example:

// read container information
MlpiContainerInformation info;
memset(&info, 0, sizeof(info));

MLPIRESULT result = mlpiContainerGetInformation(connection, hContainer, &info);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
  return result;
}

// allocate enough memory and read item information
WCHAR16 *tagList = new WCHAR16[info.numElementsTagList+1];
mlpiContainerGetTagList(connection, hContainer, tagList, info.numElementsTagList+1);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
  delete [] tagList;
  return result;
}

// print the tagList
printf("\n%s", W2A16(tagList));

delete [] tagList;

MLPIRESULT mlpiContainerGetItemInformation	(	const MLPIHANDLE	connection,
		const MlpiContainerHandle	handle,
		MlpiContainerItemInformation *	info,
		const ULONG	numElements,
		ULONG *	numElementsRet
	)

This function returns the item information of a container as an array of struct. Each element in the array contains information about a single item within the container. This includes information about type, size and offset of the item within the container data stream. You can use this function to read out information about the memory layout of the container data stream that gets returned by mlpiContainerUpdate.

Parameters

[in]	connection	Handle for multiple connections.
[in]	handle	Handle of the container. Use mlpiContainerCreate to create a container.
[out]	info	Pointer to an array where the requested information about the items will be stored.
[in]	numElements	Number of elements in 'info' available to write.
[out]	numElementsRet	Returns the number of elements actually read. This is the number of items in the container.

Returns

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

Example:

// read container information
MlpiContainerInformation info;
memset(&info, 0, sizeof(info));

MLPIRESULT result = mlpiContainerGetInformation(connection, hContainer, &info);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
  return result;
}

// allocate enough memory and read item information
ULONG numElementsRet = 0;
MlpiContainerItemInformation *itemInfos = new MlpiContainerItemInformation[info.numItems];
mlpiContainerGetItemInformation(connection, hContainer, itemInfos, info.numItems, &numElementsRet);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
  delete [] itemInfos;
  return result;
}

// loop over all items and print information of each item in the container
printf("\nOffset | Size | Type ");
printf("\n-------+------+------");
for (ULONG i=0; i<numElementsRet; i++) {
  printf("\n %6d  %5d  %4d", itemInfos[i].offset, itemInfos[i].dataSize, itemInfos[i].type);
}

delete [] itemInfos;

MLPIRESULT mlpiContainerGetSingleItemInformation	(	const MLPIHANDLE	connection,
		const MlpiContainerHandle	handle,
		const ULONG	index,
		WCHAR16 *	tag,
		const ULONG	numElements,
		MlpiContainerItemInformation *	info
	)

This function returns the item information of a single item in a container. It returns information about type, size and offset of the item within the container data stream. You can use this function to read out information about the memory layout of the container data stream that gets returned by mlpiContainerUpdate. This is similar to the function mlpiContainerGetItemInformation. But only a single item is returned including its tag.

Parameters

[in]	connection	Handle for multiple connections.
[in]	handle	Handle of the container. Use mlpiContainerCreate to create a container.
[in]	index	Index of the item to return information for. Use mlpiContainerGetInformation to read the number of available items in a container.
[out]	tag	String where the tag of the item will be stored.
[in]	numElements	Number of WCHAR16 elements in 'tag' available to write.
[out]	info	Pointer to a struct where the requested information about the item will be stored.

Returns

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

Example:

// read container information
MlpiContainerInformation info;
memset(&info, 0, sizeof(info));

MLPIRESULT result = mlpiContainerGetInformation(connection, hContainer, &info);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
  return result;
}

// loop over all items and print information of each item in the container
printf("\nOffset | Size | Type | Tag         ");
printf("\n-------+------+------+-------------");

for (ULONG i=0; i<info.numItems; i++) {
  MlpiContainerItemInformation itemInfo;
  memset(&itemInfo, 0, sizeof(itemInfo));
  WCHAR16 tag[512] = {'\0'};

  // read item info
  MLPIRESULT result = mlpiContainerGetSingleItemInformation(connection, hContainer, i, tag, _countof(tag), &itemInfo);
  if (MLPI_FAILED(result)) {
    printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
    return result;
  }

  // print it
  printf("\n %6d  %5d  %4d  %s", itemInfo.offset, itemInfo.dataSize, itemInfo.type, W2A16(tag));
}

MLPIRESULT mlpiContainerGetNumberOfContainer	(	const MLPIHANDLE	connection,
		ULONG *	number
	)

This function returns the total number of containers created on the device. Also including containers of other applications.

Parameters

[in]	connection	Handle for multiple connections.
[out]	number	Returns the total number of allocated containers on the device.

Returns

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

Example:

ULONG numContainers = 0;

// read how many containers are available
MLPIRESULT result = mlpiContainerGetNumberOfContainer(connection, &numContainers);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
   return result;
}
printf("\nFound %d container(s) on the device", numContainers);

MLPIRESULT mlpiContainerGetHandlesOfContainer	(	const MLPIHANDLE	connection,
		MlpiContainerHandle *	handles,
		const ULONG	numElements,
		ULONG *	numElementsRet
	)

Returns the handles of all containers that were previously created on the device.

Parameters

[in]	connection	Handle for multiple connections.
[out]	handles	Pointer to an array which will receive all container handles of the device.
[in]	numElements	Number of elements in 'handles' available to write.
[out]	numElementsRet	Returns the number of elements actually read. This is the number of handles returned.

Returns

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

Example:

ULONG numContainers = 0;

// read how many containers are available
MLPIRESULT result = mlpiContainerGetNumberOfContainer(connection, &numContainers);
if (MLPI_FAILED(result)) {
  printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
   return result;
}
printf("\nFound %d container(s) on the device", numContainers);

// get the handles of all containers and print the names of the containers
if (numContainers) {
  MlpiContainerHandle *containers = new MlpiContainerHandle[numContainers];

  ULONG numElementsRet = 0;
  MLPIRESULT result = mlpiContainerGetHandlesOfContainer(connection, containers, numContainers, &numElementsRet);
  if (MLPI_FAILED(result)) {
    printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
    delete [] containers;
    return result;
  }

  // print the name of each container
  for (ULONG i=0; i<numContainers; i++) {
    WCHAR16 name[K_CONTAINER_NAME_MAX_LENGTH+1];
    MLPIRESULT result = mlpiContainerGetName(connection, containers[i], name, _countof(name));
    if (MLPI_SUCCEEDED(result)) {
      printf("\n%d: %s", i, W2A16(name));
    } else {
      printf("\n%d: could not retrieve name of container", i);
    }
  }

  delete [] containers;
}