CIPrivateData

Using the CIPrivateData interface you can read and write private data, or information specific to your plug-in, to the PageMaker publication file. The data that you write is contained in a seperate storage from the publication data.

PageMaker uses Microsoft OLE technology to do this. OLE files contain data storages, and a storage can contain streams. To understand the relationship between a file, storages, and streams, you can look at them as a disk, folders, and files. As a disk will often contain multiple folders, so a file can contain multiple storages, and a storage can contain multiple streams. The streams are what contain the actual data that you have added to a publication.


CIPrivateData methods

The CIPrivateData methods allow you to work with the data streams, and storages that PageMaker stores your private data in.

PMErr OpenPrivateData(char *pName, char *dataType, unsigned long mustExist);

This method is used to open a private data stream.

char * pName;

This indicates the name of the storage.

char * dataType;

This indicates the stream within that storage. You may want to use the name of your company, or the name of your plug-in to name the storage, and an indication of how you are using the data as the name of the stream.

A plug-in developed by Adobe Systems, Inc. that stored information that is used during the creation of a PDF file might use "Adobe Systems" to name the storage and "PDF Marks" to name the stream. The storage and stream names are limited to 32 characters in length (not including the null character.)

unsigned long mustExist;

This is a boolean flag indicating whether the private data must already exist. If set to false, then PageMaker will create a new private data item with the specified name and datatype if it doesn't exist. If this flag is true, and the specified name and datatype item don't exist, this method will return an error.

PMErr OpenPrivateData(PMOBJ_REC* pObjRec, char *dataType, unsigned long mustExist);

You would use this method to open a private data stream that is attached to an object within the PageMaker publication. All of the private data for an object is stored within a single storage, and the dataType indicates the stream (as well as the type of information in the stream.

PMErr ClosePrivateData();

This is used to close the currently open data stream. Since you are only allowed to have one data stream open at a time, this method closes that stream.

PMErr DeletePrivateData(char *pName, char *dataType);

This deletes the data stream indicated. The data stream should not be opened when you use this method (doing so will return an error.)

PMErr DeletePrivateData(PMOBJ_REC* pObjRec, char *dataType);

This mehtod deletes a data stream that is associated with a particular object in the publication.

PMErr DeletePrivateDataStorage(char *pName);

This method deletes an entire storage. All of the private data within the storage specified is deleted. You should use caution when using this mehtod because it will delete all the entire storage, even data written by other plug-ins.

PMErr DeletePrivateDataStorage(PMOBJ_REC* pObjRec);

Use this to delete all of the private data associated with an object in a publication.

PMErr ReadPrivateData(void **pData, unsigned long size, unsigned long &aSize);

Reads data from the open stream. Use size to indicate how much data to read (in bytes.) The buffer is allocated in the application and the size of the buffer is returned in aSize. Set the size value to 0 if you want to read the entire stream. A NULL pointer returned in pData indicates that the stream is empty. You must free the memory allocated for the buffer, even though you do not allocate the buffer.

PMErr WritePrivateData(void *pData, unsigned long size);

This writes data to the open stream. The pointer pData points to the data you want to write to the stream, and size indicates how much of the buffer to write.

PMErr SeekPrivateData(long offset, SeekType sType);

This method will move the current position in the data stream. The value in offset is a signed value, and can indicate moving forward (positive values) or backward (negative values) through the private data in the stream. After a read or write to the stream, the new position is at the end of the data that was read or written.
Value for SeekType Position to offset from
PDSEEK_SET Offset from the beginning of the data stream.
PDSEEK_CUR Offset from the current position.
PDSEEK_END Offset from the end of the data stream.

void FreeMemory(void *lpData);

This method is a shortcut to CIBasic->PMMemFree.You must free the buffer allocated by the ReadPrivateData interface either by using this method or by calling CIBasic->PMMemFree.


Comments or suggestions? Contact Adobe Developer Support

Copyright © 1997 - 2001 Adobe Systems Incorporated. All rights reserved.
Legal notices and trademark attributions