ISharedPropertyGroupManager::CreatePropertyGroup Method (Visual C++)

ISharedPropertyGroupManager::CreatePropertyGroup Method

Creates and returns a reference to a new shared property group. If a property group with the specified name already exists, CreatePropertyGroup returns a reference to the existing group.

Provided By

ISharedPropertyGroupManager Interface

HRESULT ISharedPropertyGroup::CreatePropertyGroup (
    BSTR name,
    LONG* plIsoMode,
    LONG* plRelMode,
    VARIANT_BOOL* pfExists,
    ISharedPropertyGroup** ppGroup,
);

Parameters

name
[in] The name of the shared property group to create.

plIsoMode
[in, out] A reference to a LONG that specifies the isolation mode for the properties in the new shared property group. See the table that lists plIsoMode constants later in this topic. If the value of the pfExists parameter is set to VARIANT_TRUE on return from this method, the plIsoMode value you passed in is ignored and the value returned in this parameter is the isolation mode that was assigned when the property group was created.

plRelMode
[in, out] A reference to a LONG that specifies the release mode for the properties in the new shared property group. See the table that lists plRelMode constants later in this topic. If the value of the pfExists parameter is set to VARIANT_TRUE on return from this method, the plRelMode value you passed in is ignored and the value returned in this parameter is the release mode that was assigned when the property group was created.

pfExists
[out] A reference to a BOOL that's set to VARIANT_TRUE on return from this method if the shared property group specified in the name parameter existed prior to this call, and VARIANT_FALSE if the property group was created by this call.

ppGroup
[out] A reference to a shared property group identified by the BSTR passed in the name parameter, or NULL if an error is encountered.

Settings

The following constants are used in the plIsoMode parameter to specify the effective isolation mode for a shared property group.

Constant	Value	Description

LockSetGet	0	Default. Locks a property during a get_Value or put_Valuecall, assuring that every get or set operation on a shared property is atomic. This ensures that two clients can't read or write to the same property at the same time, but it doesn't prevent other clients from concurrently accessing other properties in the same group.
LockMethod	1	Locks all of the properties in the shared property group for exclusive use by the caller as long as the caller's current method is executing. This is the appropriate mode to use when there are interdependencies among properties, or in cases where a client may have to update a property immediately after reading it before it can be accessed again.

Note When you set the isolation mode to LockMethod, the Shared Property Manager requires access to the calling object's ObjectContext. You can't use this isolation mode to create a shared property group from within an object's constructor or from a non-MTS object because ObjectContext isn't available during object construction and a base client doesn't have an ObjectContext.

The following constants are used in the plRelMode parameter to specify the effective release mode for a shared property group.

Constant	Value	Description

Standard	0	When all clients have released their references on the property group, the property group is automatically destroyed. (This is the default COM mode.)
Process	1	The property group isn't destroyed until the process in which it was created has terminated. (Objects that hold references on a property group must still call Release on their references).

Return Values

S_OK
A reference to the shared property group specified in the name parameter is returned in the ppGroup parameter.

CONTEXT_E_NOCONTEXT
The caller isn't executing under the MTS run-time environment. A caller must be executing under MTS to use the Shared Property Manager.

E_INVALIDARG
At least one of the parameters is invalid, or the same object is attempting to create the same property group more than once.

Remarks

The CreatePropertyGroup method sets the value in pfExists to VARIANT_TRUE if the property group it returns in the ppGroup parameter existed prior to the current call. This occurs when another object in the same process has already called CreatePropertyGroup with the same property group name. The CreatePropertyGroup method sets the value in pfExists to VARIANT_FALSE if the returned property group was created by the current call.

The isolation mode and release mode are assigned when the property group is originally created and aren't changed if a subsequent call passes different values in these parameters. The caller should always check the value of pfExists on return from this method. If pfExists is set to VARIANT_TRUE, the caller should check the values returned in plIsoMode and plRelMode to determine the isolation and release modes in effect for the property group. For example:

hr = pPropGpMgr->CreatePropertyGroup(stName,
    &lIsolationMode, &lReleaseMode, &fAlreadyExists,
    &pPropGp);
if (fAlreadyExists) {
    if ((lIsolationMode != LockMethod) ||
        (lReleaseMode != Process)) {
        // Do something appropriate.
    }
}
If*

Note An object should never attempt to pass a shared property group reference to another object. If the reference is passed outside of the object that acquired it, it's no longer a valid reference.

Example