ICertAdmin::SetRequestAttributes method (certadm.h)

Article
10/13/2021

The SetRequestAttributes method sets attributes in the specified pending certificate request. This method was first defined in the ICertAdmin interface.

For this method to succeed, the certificate request must be pending.

Syntax

HRESULT SetRequestAttributes(
  [in] const BSTR strConfig,
  [in] LONG       RequestId,
  [in] const BSTR strAttributes
);

Parameters

[in] strConfig

Represents a valid configuration string for the certification authority (CA) server in the form COMPUTERNAME\CANAME, where COMPUTERNAME is the network name of the Certificate Services server and CANAME is the common name of the certification authority, as entered during Certificate Services setup. For information about the configuration string name, see ICertConfig.

Important SetRequestAttributes does not clear the internal cache when the configuration string is changed. When you change the configuration string for the CA, you must instantiate a new ICertAdmin object and call this method again with the new configuration string.

[in] RequestId

Specifies the ID of the request receiving the attributes.

[in] strAttributes

Specifies the attribute data. Each attribute is a name-value string pair. The colon character separates the name and value, and a newline character separates multiple name-value pairs, for example:

C++	AttributeName1:AttributeValue1\nAttributeName2:AttributeValue2
VB	AttributeName1:AttributeValue1 & vbNewLine & AttributeName2:AttributeValue2

There is no set limit to the number of request attributes that may be added to a request.

When Certificate Services parses attribute names, it ignores spaces, hyphens (minus signs), and case. For example, AttributeName1, Attribute Name1, and Attribute-name1 are all equivalent. For attribute values, Certificate Services ignores leading and trailing white space.

Note The maximum length for an attribute name is 127 non-NULL characters. The maximum length for an attribute value is 4,096 non-NULL characters.

Return value

VB

If the method succeeds, the method returns S_OK.

If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see Common HRESULT Values.

Remarks

Attributes added or updated by calling SetRequestAttributes do not alter the initial, unparsed attribute string associated with the certificate request. The certificate request's unparsed attribute string is unalterable after the certificate is requested (the ICertRequest::Submit method allows attributes to be specified at the time the certificate is requested).

You can use the Certification Authority MMC snap-in to display the initial unparsed request attribute string.

When you view the parsed attributes, you will also see any changes due to calls to SetRequestAttributes.

To view the parsed attributes

Open the Certification Authority MMC snap-in.
Open the Pending Requests folder.
Right-click a request, point to All Tasks, and then click View Attributes/Extensions.

To enumerate or view all of the parsed attributes, including those added by means of SetRequestAttributes, you may also use the IEnumCERTVIEWATTRIBUTE interface.

Administration tasks use DCOM. Code that calls this interface method as defined in an earlier version of Certadm.h will run on Windows-based servers as long as the client and the server are both running the same Windows operating system.

Examples

    BSTR bstrAttribs = NULL;
    BSTR bstrCA = NULL;
    long nReqID;  // request ID

    //  Specify the attributes.
    //  For example, "AttName1:AttValue1\nAttName2:AttValue2". 
    bstrAttribs = SysAllocString(L"<ATTRIBUTESHERE>");
    if (NULL == bstrAttribs)
    {
        printf("Memory allocation failed for bstrAttribs.\n");
        goto error;
    }
    
    bstrCA = SysAllocString(L"<COMPUTERNAMEHERE>\\<CANAMEHERE>");
    if (NULL == bstrCA)
    {
        printf("Memory allocation failed for bstrCA.\n");
        goto error;
    }

    //  Request ID to receive the attributes.
    nReqID = <REQUESTIDHERE>;

    //  Add these attributes to the certificate.
    //  pCertAdmin is a previously instantiated
    //  ICertAdmin object pointer. 
    hr = pCertAdmin->SetRequestAttributes( bstrCA,
                                           nReqID,
                                           bstrAttribs );
    if (FAILED(hr))
        printf("Failed SetRequestAttributes [%x]\n", hr);
    else
        printf("SetRequestAttributes succeeded\n");

    //  Done processing.

error:

    if (bstrAttribs)
        SysFreeString(bstrAttribs);
    if (bstrCA)
        SysFreeString(bstrCA);
    //  Free other resources.

Requirements

Requirement	Value
Minimum supported client	None supported
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	certadm.h (include Certsrv.h)
Library	Certidl.lib
DLL	Certadm.dll