Re: Q3Object_GetValue/SetValue API

[James W. W. <ja...@wr...>]

I have written, but not checked in, the following APIs.  They are a 
bit simpler than, say, Apple's property APIs, in that there is only 
one property tag rather than a creator and a type.  IMHO, a single 
type is enough, and it made it possible to implement the feature 
fairly easily using E3HashTable.  Is this acceptable?

In case anyone is about to object that it would be nice to 
distinguish between properties defined by Quesa and user-defined 
properties, we could use a convention like Apple's, that property 
tags consisting of all lowercase letters are reserved for official 
Quesa use.

/*!
  *	@function
  *		Q3Object_GetPropertySize
  *	@discussion
  *		Get the size of a property of an object.
  *		If the object does not have the specified property, 
the operation is
  *		considered to have failed.
  *
  *      <em>This function is not available in QD3D.</em>
  *
  *	@param	object    		The object.
  *	@param	propType		Property type tag.
  *	@param	size			Receives the size of the 
property data in bytes.
  *	@result		Success or failure of the operation.
*/
#if QUESA_ALLOW_QD3D_EXTENSIONS

Q3_EXTERN_API_C ( TQ3Status  )
Q3Object_GetPropertySize (
	TQ3Object				object,
	TQ3ObjectType			propType,
	TQ3Uns32*				size
);

#endif



/*!
  *	@function
  *		Q3Object_GetProperty
  *	@discussion
  *		Get property data from an object.
  *
  *		The operation fails if the property does not exist or 
if the provided
  *		buffer is not large enough to hold the data.
  *
  *      <em>This function is not available in QD3D.</em>
  *
  *	@param	object    		The object.
  *	@param	propType		Property type tag.
  *	@param	bufferSize		Size of provided buffer in bytes.
  *	@param	actualSize		Returns size of returned data in bytes.
  *							You may pass 
NULL if you do not need this information.
  *	@param	buffer			Buffer to receive the property data.
  *	@result		Success or failure of the operation.
*/
#if QUESA_ALLOW_QD3D_EXTENSIONS

Q3_EXTERN_API_C ( TQ3Status  )
Q3Object_GetProperty(
	TQ3Object				object,
	TQ3ObjectType			propType,
	TQ3Uns32				bufferSize,
	TQ3Uns32*				actualSize,
	void*					buffer );

#endif



/*!
  *	@function
  *		Q3Object_RemoveProperty
  *	@discussion
  *		Remove a property from an object.
  *
  *      <em>This function is not available in QD3D.</em>
  *
  *	@param	object    		The object.
  *	@param	propType		Property type tag.
  *	@result		Success or failure of the operation.
*/
#if QUESA_ALLOW_QD3D_EXTENSIONS

Q3_EXTERN_API_C ( TQ3Status  )
Q3Object_RemoveProperty(
	TQ3Object				object,
	TQ3ObjectType			propType );

#endif



/*!
  *	@function
  *		Q3Object_SetProperty
  *	@discussion
  *		Set a property of an object.  If there was already a 
property of the
  *		same type, it is replaced.
  *
  *      <em>This function is not available in QD3D.</em>
  *
  *	@param	object    		The object.
  *	@param	propType		Property type tag.
  *	@param	dataSize		Size in bytes of the data.
  *	@param	data			Data to copy into the property.
  *	@result		Success or failure of the operation.
*/
#if QUESA_ALLOW_QD3D_EXTENSIONS

Q3_EXTERN_API_C ( TQ3Status  )
Q3Object_SetProperty(
	TQ3Object				object,
	TQ3ObjectType			propType,
	TQ3Uns32				dataSize,
	const void*				data );

#endif

-- 
   James W. Walker, ScriptPerfection Enterprises, Inc.
   <http://www.write-brain.com/>