Edit

Share via

HttpUpdateServiceConfiguration function (http.h)

  • Article

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

See also

HTTP Server API Version 1.0 Functions

HTTP_SERVICE_CONFIG_ID

HTTP_SERVICE_CONFIG_SSL_CCS_SET

HTTP_SERVICE_CONFIG_SSL_SET

HTTP_SERVICE_CONFIG_SSL_SNI_SET

HttpDeleteServiceConfiguration

HttpQueryServiceConfiguration

HttpSetServiceConfiguration