Index

C/C++ Functions

pdPropAddAsExtBuffer

DT_SWORD pdPropAddAsExtBuffer(DT_PDDOC power_doc, DT_ID_SLONG obj, DT_SLONG name, const DT_UBYTE* extbuffer, DT_SLONG extlen)

Short Description: Add property - external buffer

The pdPropAddAsExtBuffer function adds a PowerDoc property to the PowerDoc object obj. This function is very similar to and compatible with pdPropAdd, which means that properties created by this function can be used in much the same capacity as if they were created by pdPropAdd. However, unlike pdPropAdd which copies the property value to a buffer that is managed by D-Type Power Engine, this function does not, meaning that the value remains in an external buffer that is under exclusive control of the application. Since the property value resides in this external buffer (i.e. outside the associated Power Engine document), the newly added property occupies a very small amount of storage space in the object obj (only the amount it takes to store the pointer and length of the external buffer).

pdPropAddAsExtBuffer is a specialized and advanced function that should be used only by applications that wish to store very large property values (e.g. large arrays or bitmap images) outside the associated Power Engine document and perform their own run-time memory management of large blocks of data. In all other cases pdPropAdd should be used instead.

Parameters

ParameterDescription

power_doc

Handle of the associated Power Engine document.

obj

Object's index in the Power Engine document.

name

A numerical value that identifies the property to be added. Can be a user-defined value or one of the predefined PowerDoc values. For a list of predefined name values, see the pdPropAdd function.

extbuffer

Pointer to an external buffer that holds the value of the property. Within the buffer, the value must be stored as native binary data (i.e. in the same format as if it was created by calling pdMakeBinary). Once this pointer is passed to pdPropAddAsExtBuffer, the location of the buffer cannot change. The buffer can be destroyed or reallocated only after the property has been removed from the object. Your application is responsible for managing and destroying the buffer. If this is not done properly, you could experience crashes, memory leaks and other similar problems.

extlen

Length of the binary data within the buffer, in bytes. Must not be negative. Although your application is allowed to change the value of the property (i.e. contents of the external buffer) at any time, its length must always remain precisely extlen bytes. Otherwise, you could experience crashes, memory access violations and other unexpected problems.

Return Value

See pdPropAdd.

Note

PowerDoc documents that contain properties created by this function should not be saved to disk by calling pdDocSaveToStream and later opened by calling pdDocAppendFromStream unless you are certain that the location of the buffer extbuffer will never change. If extbuffer changes after the document is saved and before it is opened again, you could experience crashes, memory access violations and similar problems.

Comments

See pdPropAdd.

Related Functions

pdPropAdd
pdPropGet, pdPropSet, pdPropSetAsExtBuffer
pdPropDel

 

Index