Главная » Linux

Windows http server api

Содержание
  1. HTTP Server API Overview
  2. HttpSetServiceConfiguration function (http.h)
  3. Syntax
  4. Parameters
  5. Return value
  6. Remarks
  7. HTTP_SERVER_AUTHENTICATION_INFO structure (http.h)
  8. Syntax
  9. Members
  10. Remarks
  11. Введение в REST API — RESTful веб-сервисы
  12. Вы изучите:
  13. Что такое REST?
  14. Краткий обзор HTTP
  15. Протокол HTTP
  16. HTTP и RESTful веб-сервисы
  17. Ресурс
  18. URI ресурса
  19. REST и Ресурсы
  20. Компоненты HTTP
  21. Методы HTTP-запроса
  22. Код статуса ответа HTTP
  23. Резюме

HTTP Server API Overview

The following list identifies a typical sequence of operations that use the HTTP Server API:

  • Initialize the HTTP Server API by using the HttpInitialize function.
  • Create a request queue by using the HttpCreateHttpHandle function.
  • Register one or more URLs by using the HttpAddUrl function.
  • Receive incoming requests directed to registered URLs by using the HttpReceiveHttpRequest function, and send HTTP responses for these requests by using the HttpSendHttpResponse function.
  • (Optional) When sending a response, send an additional entity body by using the HttpSendResponseEntityBody function.
  • Perform clean-up operations by using the HttpRemoveUrl, CloseHandle and HttpTerminate functions.

In operations that use URLs, note that it is the processed URL contained in the CookedUrl member of the HTTP_REQUEST_V1 structure that should be used. Do not the unprocessed URL in the pRawUrl member, which is solely for tracking and statistical purposes.

Each application creates its own request queue. An application obtains its request queue handle from HttpCreateHttpHandle. It passes this handle to the HttpAddUrl function to add a URL to the request queue. The application receives notification of an incoming request, and retrieves it from the request queue by calling the HttpReceiveHttpRequest function with the request queue handle. You can use this function to receive either the request headers or both the headers and entity body. HttpReceiveHttpRequest also returns a request identifier (RequestId) for the received request that is unique to the request handle.

It is the application’s responsibility to examine all relevant request headers, including content-negotiation headers if they are being used, and fail requests as appropriate based on header content. The HTTP Server API ensures only that each header line is properly terminated, and does not contain illegal characters.

Use the HttpReceiveRequestEntityBody function with the request queue handle to retrieve subsequent portions of a request’s entity body, if any.

The HTTP Server API decodes chunked messages on the receive side, but does not perform chunked encoding on the send side. If chunking is required on the send side, the application must implement it. For more information about chunked encoding, see RFC 2616.

Use the HttpReceiveClientCertificate function with applications that serve URLs by using a secure scheme («https«) to optionally retrieve the client’s certificate information.

Responses are sent with the HttpSendHttpResponse function. This function uses the RequestId from the corresponding request to send the response. A response can be sent in several API calls over time by calling the HttpSendResponseEntityBody function with the RequestId from the originally received request.

By default, HttpSendHttpResponse uses «Microsoft-HTTPAPI/1.0» as the «Server:» header. If an application specifies a server header in a response, that value is placed as the first part of the server header, followed by a space and then «Microsoft-HTTPAPI/1.0».

In general, the HTTP Server API hides details of connection management and their establishment and teardown from applications. However, an application can optionally detect termination of a connection by calling HttpWaitForDisconnect.

Читайте также:  Sysprep copyprofile windows 10

Applications must clean-up by using the following steps:

  • When the application is not listening or responding to a URL, the URL is removed by using the HttpRemoveURL function.
  • When the application is finished using the request queue, close the request queue handle by using the CloseHandle function.
  • When the application is finished using the HTTP Server API, call the HttpTerminate function.

HttpSetServiceConfiguration function (http.h)

The HttpSetServiceConfiguration function creates and sets a configuration record for the HTTP Server API configuration store. The call fails if the specified record already exists. To change a given configuration record, delete it and then recreate it with a different value.

Syntax

Parameters

Reserved. Must be zero.

Type of configuration record to be set. This parameter can be one of the following values from the HTTP_SERVICE_CONFIG_ID enumeration.

ConfigId value Meaning
HttpServiceConfigIPListenList Sets a record in the IP Listen List.
HttpServiceConfigSSLCertInfo Sets a specified SSL certificate record.
HttpServiceConfigUrlAclInfo Sets a URL reservation record.
HttpServiceConfigTimeout Sets a specified HTTP Server API wide connection time-out.

WindowsВ Vista and later:В В This enumeration value is supported.

HttpServiceConfigSslSniCertInfo Sets a specified SSL Server Name Indication (SNI) certificate record.

WindowsВ 8 and later:В В This enumeration value is supported.

HttpServiceConfigSslCcsCertInfo Sets 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 Transport Layer Security (TLS) handshake. The port is specified by the KeyDesc member of the HTTP_SERVICE_CONFIG_SSL_CCS_SET structure that you pass to the pConfigInformation parameter.

WindowsВ 8 and later:В В This enumeration value is supported.

A pointer to a buffer that contains the appropriate data to specify the type of record to be set.

WindowsВ Vista and later:В В This structure is supported.

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.

WindowsВ 8 and later:В В This structure is supported.

WindowsВ 8 and later:В В This structure is supported.

Size, in bytes, of the pConfigInformation buffer.

This parameter is reserved and must be NULL.

Return value

If the function succeeds, the return value is NO_ERROR.

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

ConfigId value Meaning
HttpServiceConfigIPListenList
HttpServiceConfigSslSniCertInfo
HttpServiceConfigSslCcsCertInfo
Value Meaning
ERROR_ALREADY_EXISTS The specified record already exists, and must be deleted in order for its value to be re-set.
ERROR_INSUFFICIENT_BUFFER The buffer size specified in the ConfigInformationLength 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 set with HttpSetServiceConfiguration 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.

HTTP_SERVER_AUTHENTICATION_INFO structure (http.h)

The HTTP_SERVER_AUTHENTICATION_INFO structure is used to enable server-side authentication on a URL group or server session. This structure is also used to query the existing authentication schemes enabled for a URL group or server session.

This structure must be used when setting or querying the HttpServerAuthenticationProperty on a URL group, or server session.

Syntax

Members

The HTTP_PROPERTY_FLAGS structure that specifies if the property is present.

The supported authentication schemes. This can be one or more of the following:

Authentication Scheme Meaning
HTTP_AUTH_ENABLE_BASIC Basic authentication is enabled.
HTTP_AUTH_ENABLE_DIGEST Digest authentication is enabled.
HTTP_AUTH_ENABLE_NTLM NTLM authentication is enabled.
HTTP_AUTH_ENABLE_NEGOTIATE Negotiate authentication is enabled.
HTTP_AUTH_ENABLE_KERBEROS Kerberos authentication is enabled.
HTTP_AUTH_ENABLE_ALL All types of authentication are enabled.

A Boolean value that indicates, if True, that the client application receives the server credentials for mutual authentication with the authenticated request. If False, the client application does not receive the credentials.

Be aware that this option is set for all requests served by the associated request queue.

A Boolean value that indicates, if True, that the finalized client context is serialized and passed to the application with the request. If False, the application does not receive the context. This handle can be used to query context attributes.

A Boolean value that indicates, if True, that the NTLM credentials are not cached. If False, the default behavior is preserved.

By default, HTTP caches the client context for Keep Alive (KA) connections for the NTLM scheme if the request did not originate from a proxy.

Optional authentication flags. Can be one or more of the following possible values:

Value Meaning
HTTP_AUTH_EX_FLAG_ENABLE_KERBEROS_CREDENTIAL_CACHING If set, the Kerberos authentication credentials are cached. Kerberos or Negotiate authentication must be enabled by AuthSchemes.
HTTP_AUTH_EX_FLAG_CAPTURE_CREDENTIAL If set, the HTTP Server API captures the caller’s credentials and uses them for Kerberos or Negotiate authentication. Kerberos or Negotiate authentication must be enabled by AuthSchemes.

The HTTP_SERVER_AUTHENTICATION_DIGEST_PARAMS structure that provides the domain and realm for the digest challenge.

The HTTP_SERVER_AUTHENTICATION_BASIC_PARAMS structure that provides the realm for the basic challenge.

Remarks

The HTTP_SERVER_AUTHENTICATION_INFO structure is included in the HTTP request if authentication has been configured on the associated URL group. The original HTTP authentication header received from the client is always included in the HTTP request, regardless of the authentication status.

Введение в REST API — RESTful веб-сервисы

Эта статья начинает серию постов о разработке REST API:


Intro to RESTful Web Services

REST означает REpresentational State Transfer (Википедия: «передача состояния представления»). Это популярный архитектурный подход для создания API в современном мире.

Вы изучите:

Что такое REST?

REST расшифровывается как REpresentational State Transfer. Это был термин, первоначально введен Роем Филдингом (Roy Fielding), который также был одним из создателей протокола HTTP. Отличительной особенностью сервисов REST является то, что они позволяют наилучшим образом использовать протокол HTTP. Теперь давайте кратко рассмотрим HTTP.

Краткий обзор HTTP

Давайте сначала откроем браузер и зайдем на веб-страницу:

А затем щелкните на одной из страниц результатов:

Далее мы можем нажать на ссылку на странице, на которой мы оказались:

И перейти на другую страницу:

Вот как мы обычно просматриваем веб страницы.

Когда мы просматриваем страницы в Интернете, за кулисами происходит много вещей. Ниже приведено упрощенное представление о том, что происходит между браузером и серверами, работающими на посещаемых веб-сайтах:

Протокол HTTP

Когда вы вводите в браузере URL-адрес, например www.google.com, на сервер отправляется запрос на веб-сайт, идентифицированный URL-адресом.
Затем этот сервер формирует и выдает ответ. Важным является формат этих запросов и ответов. Эти форматы определяются протоколом HTTP — Hyper Text Transfer Protocol.

Когда вы набираете URL в браузере, он отправляет запрос GET на указанный сервер. Затем сервер отвечает HTTP-ответом, который содержит данные в формате HTML — Hyper Text Markup Language. Затем браузер получает этот HTML-код и отображает его на экране.

Допустим, вы заполняете форму, присутствующую на веб-странице, со списком элементов. В таком случае, когда вы нажимаете кнопку «Submit» (Отправить), HTTP-запрос POST отправляется на сервер.

HTTP и RESTful веб-сервисы

HTTP обеспечивает базовый уровень для создания веб-сервисов. Поэтому важно понимать HTTP. Вот несколько ключевых абстракций.

Ресурс

Ресурс — это ключевая абстракция, на которой концентрируется протокол HTTP. Ресурс — это все, что вы хотите показать внешнему миру через ваше приложение. Например, если мы пишем приложение для управления задачами, экземпляры ресурсов будут следующие:

  • Конкретный пользователь
  • Конкретная задача
  • Список задач

URI ресурса

Когда вы разрабатываете RESTful сервисы, вы должны сосредоточить свое внимание на ресурсах приложения. Способ, которым мы идентифицируем ресурс для предоставления, состоит в том, чтобы назначить ему URI — универсальный идентификатор ресурса. Например:

  • Создать пользователя: POST /users
  • Удалить пользователя: DELETE /users/1
  • Получить всех пользователей: GET /users
  • Получить одного пользователя: GET /users/1

REST и Ресурсы

Важно отметить, что с REST вам нужно думать о приложении с точки зрения ресурсов:
Определите, какие ресурсы вы хотите открыть для внешнего мира
Используйте глаголы, уже определенные протоколом HTTP, для выполнения операций с этими ресурсами.

Вот как обычно реализуется служба REST:

  • Формат обмена данными: здесь нет никаких ограничений. JSON — очень популярный формат, хотя можно использовать и другие, такие как XML
  • Транспорт: всегда HTTP. REST полностью построен на основе HTTP.
  • Определение сервиса: не существует стандарта для этого, а REST является гибким. Это может быть недостатком в некоторых сценариях, поскольку потребляющему приложению может быть необходимо понимать форматы запросов и ответов. Однако широко используются такие языки определения веб-приложений, как WADL (Web Application Definition Language) и Swagger.

REST фокусируется на ресурсах и на том, насколько эффективно вы выполняете операции с ними, используя HTTP.

Компоненты HTTP

HTTP определяет следующую структуру запроса:

  • строка запроса (request line) — определяет тип сообщения
  • заголовки запроса (header fields) — характеризуют тело сообщения, параметры передачи и прочие сведения
  • тело сообщения (body) — необязательное

HTTP определяет следующую структуру ответного сообщения (response):

  • строка состояния (status line), включающая код состояния и сообщение о причине
  • поля заголовка ответа (header fields)
  • дополнительное тело сообщения (body)

Методы HTTP-запроса

Метод, используемый в HTTP-запросе, указывает, какое действие вы хотите выполнить с этим запросом. Важные примеры:

  • GET: получить подробную информацию о ресурсе
  • POST: создать новый ресурс
  • PUT: обновить существующий ресурс
  • DELETE: Удалить ресурс

Код статуса ответа HTTP

Код состояния всегда присутствует в ответе HTTP. Типичные примеры:

  • 200 — успех
  • 404 — cтраница не найдена

По этому вопросу имеется авторское видео.

Резюме

В статье приведен на верхнем уровне обзор архитектурного стиля REST. Подчеркивается тот факт, что HTTP является основным строительным блоком REST сервисов. HTTP — это протокол, который используется для определения структуры запросов и ответов браузера. Мы видели, что HTTP имеет дело главным образом с ресурсами, доступными на веб-серверах. Ресурсы идентифицируются с помощью URI, а операции над этими ресурсами выполняются с использованием глаголов, определенных протоколом HTTP.

Наконец, мы рассмотрели, как службы REST наилучшим образом используют функции, предлагаемые HTTP, для предоставления ресурсов внешнему миру. REST не накладывает никаких ограничений на форматы представления ресурсов или на определение сервиса.

Читайте также:  Mac os для системного администратора
Оцените статью
© 2024 Советы по настройке компьютера