ISharedPropertyGroup::CreatePropertyByPosition Method (Visual C++)

ISharedPropertyGroup::CreatePropertyByPosition Method

Creates a new shared property identified by a numeric index that's unique within the property group. If a shared property with the specified index already exists, CreatePropertyByPosition returns a reference to the existing one.

Provided By

ISharedPropertyGroup Interface

HRESULT ISharedPropertyGroup::CreatePropertyByPosition (
    INT index,
    VARIANT_BOOL* pfExists;
    ISharedProperty** ppProp,
);

Parameters

index
[in] The numeric index within the SharedPropertyGroup by which the new property will be referenced. You can use this index later to retrieve the shared property with the get_PropertyByPosition method.

pfExists
[out] A reference to a Boolean value. If pfExists is set to VARIANT_TRUE on return from this method, the shared property specified by index existed prior to this call. If it's set to VARIANT_FALSE, the property was created by this call.

ppProp
[out] A reference to a shared property object identified by the numeric index passed in the index parameter, or NULL if an error is encountered.

Return Values

S_OK
A reference to the shared property occupying the position specified in the index parameter is returned in the ppProp parameter.

E_INVALIDARG
One or more of the arguments passed in is invalid.

Remarks

When you create a shared property, its value is set to the default, which is a VARIANT of type VT_I4, with a value of 0.

If you create a SharedProperty object with the CreatePropertyByPosition method, you can access that property only by using the get_PropertyByPosition method. You can't assign a string name to the same property and then access it by using the get_Property method. Accessing a property by position is faster than accessing a property by using a string name because it requires less overhead.

The same shared property group can contain some SharedProperty objects that are identified by position and others that are identified by name.

Example