IAccessControl::GrantAccessRights

Merges the new ACTRL_ACCESS list with the existing access rights on the object.

HRESULT GrantAccessRights(
  PACTRL_ACCESSW pAccessList  //Pointer to the access list
);

Parameters

pAccessList: [in] Pointer to the ACTRL_ACCESSW list.

Remarks

Merging the new ACTRL_ACCESSW list with the existing access rights ensures that the object will have at least the indicated access rights. This merging consists of adding the supplied access before any of the existing rights. None of the existing rights are removed.

Following a merge, the access rights on an object are as follows:

[New Access Denied] [Old Access Denied] [New Access Allowed]

[Old Access Allowed]

GrantAccessRights uses the ACTRL_ACCESSW structure, which contains a list of access lists to write to the object. The ACTRL_ACCESSW list takes an optional property name. In the case of Windows NT objects, this property name is the string representation of the property GUID. For interfaces that do not take an ACTRL_ACCESSW parameter, an optional property name parameter is provided.

ACTRL_ACCESSW is defined as follows:

typedef struct 
    {
        ULONG                   cEntries; //# of prop access lists
        PACTRL_PROPERTY_ENTRYW  pPropertyAccessList; //pointer to 
                                //property access lists to write to 
                                //the object
    } ACTRL_ACCESSW, *PACTRL_ACCESSW, ACTRL_AUDITW, *P ACTRL_AUDITW

The pPropertyAccessList member points to an ACTRL_PROPERTY_ENTRYW structure, defined as follows:

typedef struct _ACTRL_PROPERTY_ENTRYW
    {
        LPWSTR                     lpProperty; //pointer to prop name
        PACTRL_ACCESS_ENTRY_LISTW  pAccessEntryList; //pointer to the
                                   // access entry list (may be NULL)
        ULONG                      fListFlags; //property entry info
    } ACTRL_PROPERTY_ENTRYW, *PACTRL_PROPERTY_ENTRYW

The pAccessEntryList points to an ACTRL_ACCESS_ENTRY_LISTW structure, which is defined as follows:

typedef struct _ACTRL_ACCESS_ENTRY_LISTW
    {
        ULONG                  cEntries; //number of entries
        PACTRL_ACCESS_ENTRYW    pAccessList; //pointer to entry list
    } ACTRL_ACCESS_ENTRY_LISTW, *PACTRL_ACCESS_ENTRY_LISTW

The pAccessList member points to an ACTRL_ACCESS_ENTRY structure, which is defined as follows:

typedef struct _ACTRL_ACCESS_ENTRYW
    {
        TRUSTEE_W        Trustee;            //the trustee
        ULONG            fAccessFlags;       //access entry flags
        ACCESS_RIGHTS    Access;             //access rights
        ACCESS_RIGHTS    ProvSpecificAccess; //provider-specific
                                             // access rights
        INHERIT_FLAGS    Inheritance;        //inheritance 
        LPWSTR           lpInheritProperty;  //option-inheritance type
    } ACTRL_ACCESS_ENTRYW, *PACTRL_ACCESS_ENTRYW;

The currently supported fAccessFlags flags are:

ACTRL_ACCESS_ALLOWED     0x00000001
    ACTRL_ACCESS_DENIED      0x00000002

The system-supplied implementation of GrantAccessRights (CLSID_DCOMAccessControl) requires that the cEntries member of the ACTRL_ACCESSW structure be set to exactly 1. In addition, the lpProperty member of the ACTRL_PROPERTY_ENTRYW structure must be NULL.

COM formats all character strings as UNICODE. For computers running Windows 95, you must convert all ANSI strings to UNICODE before passing them to GrantAccessRights.

QuickInfo

  Windows NT: Use version 4.0 or later.
  Windows: Available as a Windows 95 redistributable.
  Windows CE: Unsupported.
  Header: Declared in oleext.h.