ICertGetConfig::GetConfig method (certcli.h)

The GetConfig method retrieves the configuration string for a Certificate Services server.

The configuration string is the server name and certification authority (CA) name separated by a backslash (\); for example: ServerName\CAName. This configuration string can be used to refer unambiguously to a specific Certificate Services server. For more information, see Remarks.

Syntax

HRESULT GetConfig(
  LONG Flags,
  BSTR *pstrOut
);

Parameters

Flags

Value that specifies the CA to use. This parameter can be one of the following values.

Value Meaning
CC_DEFAULTCONFIG
0x00000000
Retrieves the default CA.
CC_FIRSTCONFIG
0x00000002
Returns the first CA.
CC_LOCALACTIVECONFIG
0x00000004
Retrieves the local CA if it is running.
CC_LOCALCONFIG
0x00000003
Retrieves the local CA.
CC_UIPICKCONFIG
0x00000001
Displays a user interface (UI) that allows the user to select a CA.
CC_UIPICKCONFIGSKIPLOCALCA
0x00000005
Displays a UI that allows the user to select a CA. The UI excludes any local CA. This exclusion is useful during subordinate CA certificate renewal when the subordinate CA certificate request is submitted to a CA other than the current CA.

pstrOut

A pointer to a BSTR that contains the configuration. When you have finished using the configuration, call the SysFreeString function to free pbstrOut.

Return value

If the function is successful, the return value is S_OK.

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

Remarks

The certification authority (CA) name portion of the configuration string that this function returns is the exact text entered during the Certificate Services setup process. Note that this text may be different from the form of the CA name found in file names (such as for the certificate revocation list) or in registry keys. This is because file names and registry keys use a sanitized version of the CA name.

The process of sanitizing the CA name is necessary to remove characters that are illegal for file names, registry key names, or distinguished name values, or illegal for reasons specific to Certificate Services. In the sanitizing process, any illegal character in the common name is converted to a five-character representation in the format !xxxx, where the exclamation point (!) is used as an escape character and xxxx represents four hexadecimal digits that uniquely identify the character to be converted.

For example, the number sign (#) is not allowed in distinguished names in the Active Directory directory service. If the CA name entered during setup is #YourName, the sanitized CA name will be !0023YourName.

The following characters, if entered for the common name of the CA during setup, are converted to the !xxxx format during the sanitizing process. This list is subject to change.

Character Value in !xxxx format
< !003c
> !003e
" !0022
/ !002f
\ !005c
: !003a
| !007c
? !003f
* !002a
# !0023
, !002c
+ !002b
; !003b
! !0021
 

Any nonprinting character and all Unicode characters that are not seven bits are also converted to the !xxxx format.

A sanitized short name is generated when the sanitized name is too long for a 64-character directory services relative distinguished name (RDN). The sanitized short name consists of the sanitized name truncated and appended with a hash of the full sanitized name. The sanitized short name reserves some of the 64 characters to contain certificate revocation list (CRL) suffixes, such as (123).

The CA name portion of the configuration string returned by this method is the original text entered during setup. Note that Certificate Services methods that require a CA name as a parameter accept the originally entered CA name. For example, for the CA name #YourName, the
ICertView2::OpenConnection method accepts #YourName as the parameter's CA portion.

Requirements

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

See also

ICertConfig2::GetConfig

ICertGetConfig

ICertView2::OpenConnection