This is a utility function which, according to the specified PowerDoc format identifier, converts a standard null-terminated C/C++ string to a PowerDoc property value in the native binary format (binary data). Thus, the binary data created by this function can be used as a property value when calling the pdPropAdd function.
The resulting binary data can be stored either in a user supplied memory buffer or in a memory buffer dynamically allocated by the function.
Parameter | Description |
---|---|
value |
A pointer to a null-terminated C/C++ string that will be converted to a PowerDoc property value in the native binary format. |
format |
One of the supported PowerDoc format identifiers. For a list of possible format identifiers, please see Note 1 below. |
buffer |
A valid pointer to a user supplied memory buffer that, if large enough, will hold the resulting binary data. Alternatively, this pointer can be set to DV_NULL which indicates that the user supplied buffer is not available. In this case the function will attempt to allocate the buffer for the resulting binary data dynamically. |
len |
A valid pointer to an input/output variable that provides the size of the user supplied buffer to the function and receives the length of the resulting binary data from the function, in bytes. This pointer cannot be set to DV_NULL. If the user supplied buffer is not available (i.e. buffer is set to DV_NULL), the value of the variable pointed by this pointer should be set to 0. If the user supplied buffer is available, the value of the variable pointed by this pointer should accurately reflect its size in bytes. |
dynamic |
A valid pointer to an output variable that indicates whether the buffer for the resulting binary data was allocated dynamically. Whenever the user supplied buffer is available and large enough to hold the resulting binary data, the function will use that buffer. To indicate that the resulting binary data is stored in the user supplied buffer, the function will set the variable pointed by dynamic to 0. However, if the function evaluates that the user supplied buffer is not large enough to hold the resulting binary data, the buffer will be allocated dynamically and the variable pointed by dynamic will be set to 1. In this case, the dynamically allocated buffer must be later released by calling the pdFree function. |
If the function was successful, the return value is a pointer to the memory buffer at which the resulting binary data begins. As noted earlier, this will be either a pointer to the user supplied buffer (in which case the return value will equal buffer) or a pointer to a memory buffer that the function allocated dynamically. Use the variable pointed by the dynamic pointer to determine which type of the buffer was used.
In addition, the function will return the length of the resulting binary data via the variable pointed by len.
If the function was not successful (e.g. bad input or memory error), the return value will be DV_NULL and the variables pointed by len and dynamic will be both set to 0.
Currently supported PowerDoc format identifiers:
PD_BYTE_SIGNED — a string converted to a single signed byte
PD_ARR_BYTE_SIGNED — a string converted to an array of signed bytes
Individual elements of the array should be seprated by a single comma and/or space character.
PD_BYTE_UNSIGNED — a string converted to a single unsigned byte
PD_ARR_BYTE_UNSIGNED — a string converted to an array of unsigned bytes
Individual elements of the array should be seprated by a single comma and/or space character.
PD_WORD_SIGNED — a string converted to a signed 2-byte integer
PD_ARR_WORD_SIGNED — a string converted to an array of signed 2-byte integers
Individual elements of the array should be seprated by a single comma and/or space character.
PD_WORD_UNSIGNED — a string converted to an unsigned 2-byte integer
PD_ARR_WORD_UNSIGNED — a string converted to an array of unsigned 2-byte integers
Individual elements of the array should be seprated by a single comma and/or space character.
PD_TRIO_SIGNED — a string converted to a signed 3-byte integer
PD_ARR_TRIO_SIGNED — a string converted to an array of signed 3-byte integers
Individual elements of the array should be seprated by a single comma and/or space character.
PD_TRIO_UNSIGNED — a string converted to an unsigned 3-byte integer
PD_ARR_TRIO_UNSIGNED — a string converted to an array of unsigned 3-byte integers
Individual elements of the array should be seprated by a single comma and/or space character.
PD_LONG_SIGNED — a string converted to a signed 4-byte integer
PD_ARR_LONG_SIGNED — a string converted to an array of signed 4-byte integers
Individual elements of the array should be seprated by a single comma and/or space character.
PD_LONG_UNSIGNED — a string converted to an unsigned 4-byte integer
PD_ARR_LONG_UNSIGNED — a string converted to an array of unsigned 4-byte integers
Individual elements of the array should be seprated by a single comma and/or space character.
PD_ASC — a string of ASCII characters converted to an array of bytes
PD_HEX — a string of 2-digit HEX values converted to an array of bytes.
(when applicable, the expected length of the array will be indicated)
Although PD_HEX is a general purpose format, it is used as the default storage format only for properties whose value strings cannot be conveniently represented in any other way (for example: bitmap's pixels or other binary data).
PD_DEFAULT — a string converted to the property's default storage format.
Depending on the property in question, this can be any of the above format identifiers.