IdmaProperties

This interface provides read-only access to DMA property values of any DMA base property type: Binary, Boolean, DateTime, Float, Identifier, Integer, Object, or String. Properties may be chosen either by their index in the object's class description list, or by their property identifier (e.g. dmaProp_RenditionsPresent). Both indices and property ids can be found from the object's meta-data. Some Property Ids are well known and can be used directly without investigation of the meta-data.

The methods used to access DMA Properties are segmented into two interfaces, the methods that allow readonly access to the properties (IdmaProperties), and the methods that allow modification of the properties (IdmaEditProperties).

When a caller requests the value of a property of type String, DateTime, or Binary, the called method allocates storage for the property value (using the DMA system allocator), and passes back a pointer to the allocated storage. It is the caller's responsibility to free that storage when it is no longer needed -- again using the DMA system allocator.

IdmaProperties::GetPropValBinaryById

Support for this method is optional.

Syntax
DmaRC IdmaProperties::GetPropValBinaryById (
pDmaId pPropertyId,
DmaBinaryValue* pBinaryValue)

Parameters

Returns a binary property value -- a fixed number of bytes of arbitrary format. This is one of the basic data types used for property values. The property of interest is located using its identifier, which is either "well-known" or obtained from the meta-data.

The caller is responsible for allocating and freeing the structure pointed to by the pBinaryValue parameter. The memory pointed to by the pBinaryValue->pbBytes field is allocated by the callee and must be freed by the caller. This field need not be pre-initialised to NULL by the caller, and must be set to NULL by the callee if any return code other than DMARC_OK is returned.

Return Values

IdmaProperties::GetPropValBinaryByIndex

Support for this method is optional.

Syntax
DmaRC IdmaProperties::GetPropValBinaryByIndex (
DmaIndex32 iIndex,
DmaBinaryValue* pBinaryValue)

Parameters

Returns a binary property value -- a fixed number of bytes of arbitrary format. This is one of the basic data types used for property values. The property of interest is located using its index, which is defined by the object's Class Description.

The caller is responsible for allocating and freeing the structure pointed to by the pBinaryValue parameter. The memory pointed to by the pBinaryValue->pbBytes field is allocated by the callee and must be freed by the caller. This field need not be pre-initialised to NULL by the caller, and must be set to NULL by the callee if any return code other than DMARC_OK is returned.

Return Values

IdmaProperties::GetPropValBooleanById

Support for this method is optional.

Syntax
DmaRC IdmaProperties::GetPropValBooleanById (
pDmaId pPropertyId,
pDmaBoolean pbBooleanValue)

Parameters

Returns a boolean property value. This is one of the basic data types used for property values. The property of interest is located using its identifier, which is either "well-known" or obtained from the meta-data.

Return Values

IdmaProperties::GetPropValBooleanByIndex

Support for this method is optional.

Syntax
DmaRC IdmaProperties::GetPropValBooleanByIndex (
DmaIndex32 iIndex,
pDmaBoolean pbBooleanValue)

Parameters

Returns a boolean property value. This is one of the basic data types used for property values. The property of interest is located using its index, which is defined by the object's Class Description.

Return Values

IdmaProperties::GetPropValDateTimeById

Support for this method is optional.

Syntax
DmaRC IdmaProperties::GetPropValDateTimeById (
pDmaId pPropertyId,
ppDmaDateTime ppDateTimeValue)

Parameters

Returns a DateTime property value, which is a specialization of a DMAString. This is one of the basic data types used for property values. The property of interest is located using its identifier, which is either "well-known" or obtained from the meta-data.

This method, if successful, allocates a DmaDateTime and passes ownership to the caller.

Return Values

IdmaProperties::GetPropValDateTimeByIndex

Support for this method is optional.

Syntax
DmaRC IdmaProperties::GetPropValDateTimeByIndex (
DmaIndex32 iIndex,
ppDmaDateTime ppDateTimeValue)

Parameters

Returns a DateTime property value, which is a specialization of DMAString. The property of interest is located using its index, which is defined by the object's Class Description.

This method, if successful, allocates a DmaDateTime and passes ownership to the caller.

Return Values

IdmaProperties::GetPropValFloat64ById

Support for this method is optional.

Syntax
DmaRC IdmaProperties::GetPropValFloat64ById (
pDmaId pPropertyId,
pDmaFloat64 pfFloatValue)

Parameters

Returns a 64 bit float property Value. This is one of the basic data types used for property values. The property of interest is located using its identifier, which is either "well-known" or obtained from the meta-data.

Return Values

IdmaProperties::GetPropValFloat64ByIndex

Support for this method is optional.

Syntax
DmaRC IdmaProperties::GetPropValFloat64ByIndex (
DmaIndex32 iIndex,
pDmaFloat64 pfFloatValue)

Parameters

Returns a 64 bit float property Value. This is one of the basic data types used for property values. The property of interest is located using its index, which is defined by the object's Class Description.

Return Values

IdmaProperties::GetPropValIdById

Support for this method is optional.

Syntax
DmaRC IdmaProperties::GetPropValIdById (
pDmaId pPropertyId,
pDmaId pIdValue)

Parameters

Returns a Property Value in DMA Id form. This is one of the basic data types used for property values. The property of interest is located using its identifier, which is either "well-known" or obtained from the meta-data.

Return Values

IdmaProperties::GetPropValIdByIndex

Support for this method is optional.

Syntax
DmaRC IdmaProperties::GetPropValIdByIndex (
DmaIndex32 iIndex,
pDmaId pIdValue)

Parameters

Returns a Property Value as a DMA Id, which is one of the basic data types used for property values. The property of interest is located using its index, which is defined by the object's Class Description.

Return Values

IdmaProperties::GetPropValInteger32ById

Support for this method is optional.

Syntax
DmaRC IdmaProperties::GetPropValInteger32ById (
pDmaId pPropertyId,
pDmaInteger32 plIntegerValue)

Parameters

Returns a 32 bit signed integer property value. This is one of the basic data types used for property values. The property of interest is located using its identifier, which is either "well-known" or obtained from the meta-data.

Return Values

IdmaProperties::GetPropValInteger32ByIndex

Support for this method is optional.

Syntax
DmaRC IdmaProperties::GetPropValInteger32ByIndex (
DmaIndex32 iIndex,
pDmaInteger32 plIntegerValue)

Parameters

Returns a 32 bit signed integer property value. This is one of the basic data types used for property values. The property of interest is located using its index, which is defined by the object's Class Description.

Return Values

IdmaProperties::GetPropValObjectById

Support for this method is optional.

Syntax
DmaRC IdmaProperties::GetPropValObjectById (
pDmaId pPropertyId,
DMA_REFIID riid,
pDmapv ppIObjectValue)

Parameters

Returns an object valued property. This operation will be successful only for properties that are of type "object". This allows properties to be containers, lists of property values, or complex types. The property of interest is located using its identifier, which is either "well-known" or obtained from the meta-data.

If the returned object does not support the interface specified by riid, the operation will fail and the result code DMARC_BAD_INTERFACE will be returned. In case the operation is successful, the returned interface must be released using the method IUnknown::Release.

The returned object is obtained by reference. If there is an already-bound value for the object-valued property, an interface on that value is returned. If there is no already-bound value, and a value is defined, an appropriate DMA object is obtained, bound, and its selected interface returned. Sometimes, an existing object will be bound (i.e., for the dmaProp_This property). In other cases, a completely new object may be supplied, as for the default initial value of a never-set list-valued property. And at other times, a new scratchpad of an existing persistent object will be created and bound in conformance with the by-reference rules of the DMA object model.

An exception is made for enumeration objects -- all access to enumeration-valued properties return interfaces to a fresh enumeration object reset to the beginning of the sequence. Enumeration-valued properties always behave as if they are not already bound.

If this method is applied to a list or enumeration property, it may never return DMARC_VALUE_NOT_SET. That is, all other error conditions notwithstanding, an interface to a list or enumeration object must always be delivered, even though the list or enumeration may be empty.

Return Values

IdmaProperties::GetPropValObjectByIndex

Support for this method is optional.

Syntax
DmaRC IdmaProperties::GetPropValObjectByIndex (
DmaIndex32 iIndex,
DMA_REFIID riid,
pDmapv ppIObjectValue)

Parameters

Returns an object valued property. This operation will be successful only for properties that are of type "object". This allows properties to be containers, lists of property values, or complex types. The property of interest is located using its index, which is defined by the object's Class Description.

If the returned object does not support the interface specified by riid, the operation will fail and the result code DMARC_BAD_INTERFACE will be returned. In case the operation is successful, the returned interface must be released using the method IUnknown::Release.

The returned object is obtained by reference. If there is an already-bound value for the object-valued property, an interface on that value is returned. If there is no already-bound value, and a value is defined, an appropriate DMA object is obtained, bound, and its selected interface returned. Sometimes, an existing object will be bound (i.e., for dmaProp_This). In other cases, a completely new object may be supplied, as for the default initial value of a never-set list-valued property. And at other times, a new scratchpad of an existing persistent object will be created and bound in conformance with the by-reference rules of the DMA object model.

An exception is made for enumeration objects -- all access to enumeration-valued properties return interfaces to a fresh enumeration object reset to the beginning of the sequence. Each time the property is accessed, enumeration-valued properties behave as if they are not already bound.

If this method is applied to a list or enumeration property, it may never return DMARC_VALUE_NOT_SET. That is, all other error conditions notwithstanding, an interface to a list or enumeration object must always be delivered, even though the list or enumeration may be empty.

Return Values

IdmaProperties::GetPropValStringById

Support for this method is optional.

Syntax
DmaRC IdmaProperties::GetPropValStringById (
pDmaId pPropertyId,
ppDmaString ppStringValue)

Parameters

Returns a DMAString-valued property value. This is one of the basic data types used for property values. The property of interest is located using its identifier, which is either "well-known" or obtained from the meta-data.

This method, if successful, allocates a DmaString and passes ownership to the caller.

Return Values

IdmaProperties::GetPropValStringByIndex

Support for this method is optional.

Syntax
DmaRC IdmaProperties::GetPropValStringByIndex (
DmaIndex32 iIndex,
ppDmaString ppStringValue)

Parameters

Returns a DMAString-valued property value, which is one of the basic data types used for property values. The property of interest is located using its index, which is defined by the object's Class Description.

This method, if successful, allocates a DmaString and passes ownership to the caller.

Return Values