ISharedPropertyGroup::CreatePropertyByPosition method (comsvcs.h)

Article
02/22/2024

Creates a new shared property with the specified index. If a shared property with the specified index already exists, CreatePropertyByPosition returns a reference to the existing one.

Syntax

HRESULT CreatePropertyByPosition(
  [in]  int             Index,
  [out] VARIANT_BOOL    *fExists,
  [out] ISharedProperty **ppProp
);

Parameters

[in] Index

The numeric index within the SharedPropertyGroup object by which the new property is referenced. You can use this index later to retrieve the shared property with the get_PropertyByPosition method.

[out] fExists

A reference to a Boolean value. If fExists is set to VARIANT_TRUE on return from this method, the shared property specified by Index existed prior to this call. If it is set to VARIANT_FALSE, the property was created by this call.

[out] ppProp

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 value

This method can return the standard return values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, E_FAIL, and S_OK.

Remarks

When you create a shared property, its value is set to the default, which is a VT_I4 VARIANT 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 cannot 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.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	comsvcs.h