Index

C/C++ Functions

pdMakeBinary

DT_UBYTE* pdMakeBinary(const DT_CHAR* value, DT_ID_SLONG format, DT_UBYTE* buffer, DT_SLONG* len, DT_UBYTE* dynamic)

Short Description: Make binary buffer

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.

Parameters

ParameterDescription

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.

Return Value

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.

Note 1

Currently supported PowerDoc format identifiers:

PD_BYTE_SIGNED — a string converted to a single signed byte

Operating Range:
-128 to 127
Valid Examples:
"80",  "-50",  "0",  "100",  "-100"
Invalid Examples:
"-500",  "130",  "3.8",  "0.002",  "5E4"

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.

Operating Range:
-128 to 127 for each array element
Valid Examples:
"20, 40, 60, 80",  "-10 -20 -30 0 50 80 90"
Invalid Examples:
"-500, 130, 3.8",  "0.00 5E4 -2"

PD_BYTE_UNSIGNED — a string converted to a single unsigned byte

Operating Range:
0 to 255
Valid Examples:
"120",  "50",  "0",  "100"
Invalid Examples:
"-2",  "350",  "3.8",  "0.002",  "5E4"

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.

Operating Range:
0 to 255 for each array element
Valid Examples:
"20, 40, 160, 220",  "100 200 250 180"
Invalid Examples:
"0 -20 0 520 50 280 -90",  "0.00 5E4 -2"

PD_WORD_SIGNED — a string converted to a signed 2-byte integer

Operating Range:
-32,768 to 32,767
Valid Examples:
"1000",  "-30150",  "0",  "-100"
Invalid Examples:
"-40000",  "40000",  "3.8",  "0.002",  "5E4"

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.

Operating Range:
-32,768 to 32,767 for each array element
Valid Examples:
"0, 600, 25000, -30000, -50 31000",  "-200 20000"
Invalid Examples:
"0 60000 2e2 -0.6",  "33000, -33000"

PD_WORD_UNSIGNED — a string converted to an unsigned 2-byte integer

Operating Range:
0 to 65,535
Valid Examples:
"20000",  "50",  "0",  "100"
Invalid Examples:
"-50",  "150000",  "3.8",  "0.002",  "5E4"

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.

Operating Range:
0 to 65,535 for each array element
Valid Examples:
"1, 2, 3",  "50000 60000 120 5000"
Invalid Examples:
"-1, -2, -3, -4",  "0.5 -2E2 70000"

PD_TRIO_SIGNED — a string converted to a signed 3-byte integer

Operating Range:
-8,388,608 to 8,388,607
Valid Examples:
"10000",  "-300800",  "0",  "-100"
Invalid Examples:
"-9000000",  "9000000",  "3.8",  "0.002",  "5E4"

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.

Operating Range:
-8,388,608 to 8,388,607 for each array element
Valid Examples:
"0, 600, 25000, -30000, -50 31000",  "-200 20000"
Invalid Examples:
"0 15000000 2e2 -0.6",  "9000000, -9000000"

PD_TRIO_UNSIGNED — a string converted to an unsigned 3-byte integer

Operating Range:
0 to 16,777,216
Valid Examples:
"14000000",  "50",  "0",  "100"
Invalid Examples:
"-50",  "17000000",  "3.8",  "0.002",  "5E4"

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.

Operating Range:
0 to 16,777,216 for each array element
Valid Examples:
"1, 2, 3",  "50000 60000 120 5000"
Invalid Examples:
"-1, -2, -3, -4",  "0.5 -2E2 17000000"

PD_LONG_SIGNED — a string converted to a signed 4-byte integer

Operating Range:
-2,147,483,648 to 2,147,483,647
Valid Examples:
"1555000",  "-4110000",  "0",  "-100"
Invalid Examples:
"-5000000000",  "3000000000",  "3.8",  "0.002",  "5E4"

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.

Operating Range:
-2,147,483,648 to 2,147,483,647 for each array element
Valid Examples:
"-1500400200, 2000000000, 80",  "0 0 0 0 0"
Invalid Examples:
"2147483648, 0",  "0.001 -3.2 5E7 2000"

PD_LONG_UNSIGNED — a string converted to an unsigned 4-byte integer

Operating Range:
0 to 4,294,967,295
Valid Examples:
"120",  "50",  "0",  "4000000000"
Invalid Examples:
"-50",  "5000000000",  "3.8",  "0.002",  "5E4"

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.

Operating Range:
0 to 4,294,967,295 for each array element
Valid Examples:
"500, 4294967295, 0",  "100 100 100 100 100 100 100 100 100"
Invalid Examples:
"-1, -2, -3",  "0.2 abc 8123222100",  "500, 4294967296, 0"

PD_ASC — a string of ASCII characters converted to an array of bytes

Valid Examples:
"test",  "1e345fg6",  "x y z",  "- / $ \ +"

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).

Valid Examples:
"23A4E8",  "23 A4 E8",  "23 a4 e8",  "F2 e5 14 C4 e8"
Invalid Examples:
"23 A4 E",  "12mk34",  "-50 e8",  "a2.05"

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.

 

Index