HttpUpdateServiceConfiguration function (http.h)

Article
10/13/2021

Updates atomically a service configuration parameter that specifies a Transport Layer Security (TLS) certificate in a configuration record within the HTTP Server API configuration store.

Syntax

HTTPAPI_LINKAGE ULONG HttpUpdateServiceConfiguration(
  [in] HANDLE                 Handle,
  [in] HTTP_SERVICE_CONFIG_ID ConfigId,
  [in] PVOID                  ConfigInfo,
  [in] ULONG                  ConfigInfoLength,
  [in] LPOVERLAPPED           Overlapped
);

Parameters

[in] Handle

Reserved and must be NULL.

[in] ConfigId

The type of configuration record to update. This parameter can be one of the following values from the HTTP_SERVICE_CONFIG_ID enumeration.

ConfigId value	Meaning
HttpServiceConfigSSLCertInfo	Updates a specified SSL certificate record.
HttpServiceConfigSslSniCertInfo	Updates a specified SSL Server Name Indication (SNI) certificate record.
HttpServiceConfigSslCcsCertInfo	Updates the SSL certificate record that specifies that Http.sys should consult the Centralized Certificate Store (CCS) store to find certificates if the port receives a TLS handshake. The port is specified by the KeyDesc member of the HTTP_SERVICE_CONFIG_SSL_CCS_SET structure that you pass to the pConfigInfo parameter.

[in] ConfigInfo

A pointer to a buffer that contains the appropriate data to specify the type of record to update. The following table shows the type of data the buffer contains for the different possible values of the ConfigId parameter.

ConfigId value	Type of data in the pConfigInfo buffer
HttpServiceConfigSSLCertInfo	HTTP_SERVICE_CONFIG_SSL_SET structure.
HttpServiceConfigSslSniCertInfo	HTTP_SERVICE_CONFIG_SSL_SNI_SET structure. The hostname will be "*" when the SSL central certificate store is queried and wildcard bindings are used, and a host name for regular SNI.
HttpServiceConfigSslCcsCertInfo	HTTP_SERVICE_CONFIG_SSL_CCS_SET structure. This structure is used to add the CCS store on the specified port, as well as to delete, retrieve, or update an existing SSL CCS record.

[in] ConfigInfoLength

The size, in bytes, of the ConfigInfo buffer.

[in] Overlapped

Reserved and must be NULL.

Return value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is one of the following error codes.

Value	Meaning
ERROR_FILE_NOT_FOUND	The specified record does not exist.
ERROR_INSUFFICIENT_BUFFER	The buffer size specified in the ConfigInfoLength parameter is insufficient.
ERROR_INVALID_HANDLE	The ServiceHandle parameter is invalid.
ERROR_INVALID_PARAMETER	One or more of the supplied parameters is in an unusable form.
ERROR_NO_SUCH_LOGON_SESSION	The SSL Certificate used is invalid. This can occur only if the HttpServiceConfigSSLCertInfo parameter is used.
Other	A system error code defined in WinError.h.

Remarks

The configuration parameters that you update with HttpUpdateServiceConfiguration are applied to all the HTTP Server API applications on the machine, and persist when the HTTP Server API shuts down, or when the computer is restarted.

Requirements

Requirement	Value
Minimum supported client	Windows 10, version 1703 [desktop apps only]
Minimum supported server	None supported
Target Platform	Windows
Header	http.h
Library	Httpapi.lib
DLL	Httpapi.dll