PreflightObjectID Class Reference

#include <PreflightObjectID.h>

Public Types
enum	{ kSmallInstanceDataSize = 16 }
typedef object_type	data_type

Public Member Functions
	PreflightObjectID ()
	PreflightObjectID (PreflightObjectClassID classID, PreflightDocumentID docID, uint32 instanceDataSize=0, const char *instanceData=nil)
	PreflightObjectID (char *serializedData, uint32 dataSize)
	PreflightObjectID (const PreflightObjectID &other)
	~PreflightObjectID ()
bool32	IsNil () const
PreflightObjectClassID	GetClassID () const
void	SetClassID (const PreflightObjectClassID &x)
PreflightDocumentID	GetDocumentID () const
void	SetDocumentID (const PreflightDocumentID &x)
uint32	GetHash () const
uint32	GetInstanceDataSize () const
const void *	GetInstanceData () const
bool32	SetInstanceData (uint32 dataSize, const void *pData)
bool32	SerializeFrom (uint32 sizeOfData, const void *serializedData)
uint32	GetSerializedSize () const
bool32	SerializeTo (uint32 sizeOfData, char *serializedData) const
PreflightObjectID &	operator= (const PreflightObjectID &other)
int	operator== (const PreflightObjectID &other) const
int	operator!= (const PreflightObjectID &other) const
int	operator< (const PreflightObjectID &other) const

Protected Member Functions
void	RecalcHash ()
bool32	SetInstanceDataSize (uint32 dataSize, bool32 preserveData=kTrue)

Detailed Description

A preflight object is simply a collection of (a) the class of the object; (b) the document the object belongs to; and (c) the instance of that object in the doucment. The instance is just basically some variable sized array of bytes that only the preflight object model service for the class can interpret. The document ID is here simply because every single object needs to know this and we don't want to include the overhead of maintaining that in the instance data for all services.

You can think of the preflight object ID as a kind of URL to something that can be anywhere from really big (a document, say) to something tiny (a single stroke).

Generally you'll use this class directly just as intended – as an opaque object. There are three things you can legitimately do with a PreflightObjectID that you don't 'own' (ie you're not an object model service and this is a ClassID you implement):

- Get its class via GetClassID() and compare it to something you know about.

    For example, you can determine whether a given object is a document using

    (objid.GetClassID() == kPreflightOM_Document).



- Get the document it's associated with and ask more information about that 

    document via IPreflightManager, which maintains the document ID map.



- Get an IPreflightObject interface via the preflight object model and use 

    that to query other info interfaces and/or call GetModelRef() to get a 

    pointer into the InDesign object model.

So for example if you have an PreflightObjectID it's fine to do something like this:

PMString GetDocumentName(const PreflightObjectID& objID)

{

    if (objID.GetClassID() == kPreflightOM_Document)

    {

        InterfacePtr<IPreflightObjectModel> iModel(Utils<IPreflightUtils>()->QueryObjectModel());

        InterfacePtr<IPreflightObject> iObj(iModel->QueryObject(objID));

        InterfacePtr<IDocument> iDoc(iObj->GetModelRef());

        ASSERT(iDoc);

        return iDoc->GetName();

    }



    ASSERT_FAIL("This isn't a document.");

    return PMString();

}

In the vast majority of cases the code that needs to use a PreflightObjectID is a rule implementation. Rules are passed the PreflightObjectID via IPreflightRuleVisitor::Visit. You can look at the object ID or query the object directly from the helper interface passed to that method.

The other class of code that needs access to PreflightObjectIDs are object model services. If you're writing an object model service, ie a service that extends the preflight object model to include custom objects (or simply objects it doesn't currently support), you can feel free to subclass PreflightObjectID to make packing and unpacking your private data easier. For example if your private data consists of a UID and an offset uint32, you might subclass PreflightObjectID with a setter (takes a UID and uint32 and calls SetInstanceData()) and a getter (calls GetInstanceData and returns a UID and uint32). But this would be purely optional, and you should not expose the details of your private data any wider than necessary. If it's necessary to allow other parties to create object IDs corresponding to your objects, you should create a utils function for that purpose. The "getter" for a PreflightObjectID should be the data interfaces it exposes via IPreflightObject.

Finally, there are utilities that will create object IDs corresponding to known InDesign objects, should you need to do this (generally speaking, only object model services, but there may be other clients).

See Also

IPreflightObjectModelUtils for this purpose.

Member Enumeration Documentation

anonymous enum

Any allocations that are this number of bytes or less do not require a separate data buffer. This is done for speed and to limit memory fragmentation. Most objects do not require a separate buffer.

Constructor & Destructor Documentation

PreflightObjectID::PreflightObjectID

(

)

Constructs an empty/zero/invalid ID.

PreflightObjectID::PreflightObjectID	(	PreflightObjectClassID	classID,
		PreflightDocumentID	docID,
		uint32	instanceDataSize = 0,
		const char *	instanceData = nil
	)

Constructs an ID with or without initial data. The only callers of this ctor should be object model services or their related utilities. Otherwise you run the risk of severely confusing the object model service that is the owner of that object class.

Parameters

classID	IN The class ID of the object.
docID	IN The ID of the document this object is associated with.
instanceDataSize	IN The size of the instance data. If 0, there is no instance data.
instanceData	IN The instance data to copy in. If nil, the object's data is initialized to zeros.

PreflightObjectID::PreflightObjectID	(	char *	serializedData,
		uint32	dataSize
	)

Constructs an ID directly from serialized data. Call this only if you know the data you're pointing at via serializedData was created via SerializeTo().

Parameters

serializedData	IN The data buffer written out via SerializeTo().
dataSize	IN The size of the data buffer. This must match the size expected (ie GetSerializedSize()) and is used as extra insurance against inadvertent coding/buffer errors.

PreflightObjectID::PreflightObjectID

(

const PreflightObjectID &

other

)

Constructs a copy of another ID. This is generally fast, but if the object has a lot of instance data it will force an extra malloc for the copy.

Parameters

other

IN The preflight object ID to copy from.

PreflightObjectID::~PreflightObjectID

(

)

Destructor. Will free the associated instance data buffer, if there is one.

Member Function Documentation

PreflightObjectClassID PreflightObjectID::GetClassID ( void  ) const

inline

Get the class ID of the object.

Returns

The class ID.

PreflightDocumentID PreflightObjectID::GetDocumentID ( ) const

inline

Get the document ID of the object. From this, via the IPreflightManager, you can obtain the actual database, IDocument, and/or path to the file. Note that you can have an object ID for an object in a document that is not currently open.

Returns

The document ID.

const void* PreflightObjectID::GetInstanceData

(

)

const

Get a pointer to the instance data. This pointer is valid only as long as the object does AND its instance data remains constant (ie SetInstanceData may make an existing pointer invalid).

Typically this is used ONLY by the object model service as part of its unpacking. For example if the object data is simply a uint32 you can cast the result to a const uint32*.

Returns

A pointer to the instance data.

uint32 PreflightObjectID::GetInstanceDataSize

(

)

const

Get the size of the instance data for this object. This simply returns the value provided via SetInstanceData().

Returns

The instance data size, in bytes.

uint32 PreflightObjectID::GetSerializedSize

(

)

const

Returns

the number of bytes required for serialization of this object.

bool32 PreflightObjectID::IsNil

(

)

const

Returns

true if the object is in a default (unconstructed) state; false if it is not.

int PreflightObjectID::operator!=

(

const PreflightObjectID &

other

)

const

Inequality is always the inverse of equality.

int PreflightObjectID::operator<

(

const PreflightObjectID &

other

)

const

Less-than is provided to support sets and maps of object IDs.

PreflightObjectID& PreflightObjectID::operator=

(

const PreflightObjectID &

other

)

The assignment operator is generally fast, although it may require an extra malloc if the instance data exceeds the internal small buffer. May free memory as well if the instance data buffer is no longer needed.

int PreflightObjectID::operator==

(

const PreflightObjectID &

other

)

const

Equality checks all parameters (ie class, doc, and instance data must match).

void PreflightObjectID::RecalcHash ( )

protected

Recalculates the internal hash value. Called automatically when any of the parameters or instance data are modified.

bool32 PreflightObjectID::SerializeFrom	(	uint32	sizeOfData,
		const void *	serializedData
	)

Replace all of the parameters (classID, docID, instanceData) with values from a serialized storage buffer. That buffer must have been set up via SerializeTo().

Parameters

sizeOfData	IN The number of bytes to read from the buffer. Must match the expected size (ie GetSerializedSize()). The method will not read past this memory size but will fail if there is not the correct number of bytes in the buffer.
serializedData	IN The data buffer to read from. Can't be nil.

Returns

kTrue if successful, or kFalse if there was a buffer problem.

bool32 PreflightObjectID::SerializeTo	(	uint32	sizeOfData,
		char *	serializedData
	)		const

Write the object's parameters out to a memory buffer.

Parameters

sizeOfData	IN The number of bytes to write. This should be the same value as returned from GetSerializedSize() and is required here as extra insurance against buffer configuration logic errors.
serializedData	OUT Receives the serialized data.

Returns

kTrue if successful or kFalse if there were size or nil ptr problems.

void PreflightObjectID::SetClassID ( const PreflightObjectClassID &  x )

inline

Set the class ID of the object. Like the instance data, only object model services and their related utilities should call this method.

Parameters

x	IN The new class ID.

void PreflightObjectID::SetDocumentID ( const PreflightDocumentID &  x )

inline

Set the document ID of the object. Like the instance data, only object model services and their related utilities should call this method.

See Also

IPreflightManager::GetDocumentID().

Parameters

x	IN The new document ID.

bool32 PreflightObjectID::SetInstanceData	(	uint32	dataSize,
		const void *	pData
	)

Sets the instance data by copying in new data.

Parameters

dataSize	The new size of the data.
pData	The data to copy in. If nil, zeros out the new data.

Returns

kTrue if sucessful; will fail only if we can't allocate memory, which would be odd.

bool32 PreflightObjectID::SetInstanceDataSize ( uint32  dataSize, bool32  preserveData = kTrue  )

protected

Internal-only helper function.