HttpCreateRequestQueue 関数 (http.h)

[アーティクル]
08/24/2023

HttpCreateRequestQueue 関数は、新しい要求キューを作成するか、既存の要求キューを開きます。

この関数は、HTTP バージョン 1.0 HttpCreateHttpHandle 関数を置き換えます。

構文

HTTPAPI_LINKAGE ULONG HttpCreateRequestQueue(
  [in]           HTTPAPI_VERSION      Version,
  [in, optional] PCWSTR               Name,
  [in, optional] PSECURITY_ATTRIBUTES SecurityAttributes,
  [in, optional] ULONG                Flags,
  [out]          PHANDLE              RequestQueueHandle
);

パラメーター

[in] Version

要求キューのバージョンを示すHTTPAPI_VERSION構造体。バージョン 2.0 の場合は、構造体のインスタンスを宣言し、 HttpCreateRequestQueue に渡す前に定義済みの値HTTPAPI_VERSION_2に設定します。

バージョンは 2.0 である必要があります。 HttpCreateRequestQueue では、バージョン 1.0 要求キューはサポートされていません。

[in, optional] Name

要求キューの名前。長さ (バイト単位) は、MAX_PATHを超えることはできません。

省略可能な name パラメーターを使用すると、他のプロセスが名前で要求キューにアクセスできます。

[in, optional] SecurityAttributes

要求キューのアクセス許可を含む SECURITY_ATTRIBUTES 構造体へのポインター。

既存の要求キューを開く場合、このパラメーターは NULL である 必要があります。

[in, optional] Flags

flags パラメーターは、要求キューのスコープを定義します。このパラメーターには、次の 1 つ以上を指定できます。

値	意味
HTTP_CREATE_REQUEST_QUEUE_FLAG_CONTROLLER	このフラグを使用して作成された要求キューへのハンドルを使用して、I/O 操作を実行することはできません。このフラグは、要求キューハンドルが作成された場合にのみ設定できます。
HTTP_CREATE_REQUEST_QUEUE_FLAG_OPEN_EXISTING	HTTP_CREATE_REQUEST_QUEUE_FLAG_OPEN_EXISTING フラグを使用すると、アプリケーションは既存の要求キューを名前で開き、要求キューハンドルを取得できます。 pName パラメーターには、有効な要求キュー名が含まれている必要があります。NULL にすることはできません。

[out] RequestQueueHandle

要求キューへのハンドルを受け取る変数へのポインター。このパラメーターには有効なポインターが含まれている必要があります。 NULL にすることはできません。

戻り値

関数が成功した場合は、NO_ERRORを返します。

関数が失敗した場合は、次のいずれかのエラーコードが返されます。

値	意味
ERROR_REVISION_MISMATCH	Version パラメーターに無効なバージョンが含まれています。
ERROR_INVALID_PARAMETER	要求キュー名の長さ (バイト単位) は、MAX_PATHを超えることはできません。既存の要求キューを開くとき、pSecurityAttributes パラメーターは NULL である必要があります。 HTTP_CREATE_REQUEST_QUEUE_FLAG_CONTROLLERは、要求キューが作成されたときにのみ設定できます。 HTTP_CREATE_REQUEST_QUEUE_FLAG_OPEN_EXISTINGは、アプリケーションに既存の要求キューを開くアクセス許可がある場合にのみ設定できます。この場合、 pReqQueueHandle パラメーターは有効なポインターである必要があり、 pName パラメーターには有効な要求キュー名が含まれている必要があります。 NULL にすることはできません。 HttpCreateRequestQueue によって返される pReqQueueHandle パラメーターは NULL です。
ERROR_ALREADY_EXISTS	pName パラメーターは、同じ名前を含む既存の要求キューと競合します。
ERROR_ACCESS_DENIED	呼び出し元プロセスには、要求キューを開くアクセス許可がありません。
ERROR_DLL_INIT_FAILED	アプリケーションは、HttpCreateRequestQueue を呼び出す前に HttpInitialize を呼び出していません。

注釈

HTTP Server API では、バージョン 1.0 の要求キューを使用する既存のアプリケーションがサポートされていますが、HTTP Server API を使用した新しい開発では 、HttpCreateRequestQueue を使用して要求キューを作成する必要があります。 HttpCreateHttpHandle は使用しないでください。バージョン 2.0 API は、 HttpCreateRequestQueue によって作成されたバージョン 2.0 要求キューとのみ互換性があります。

HTTP バージョン 2 要求キューには手動構成が必要です。アプリケーションは、 HTTPSetUrlGroupProperty を HttpServerBindingProperty と呼び出して、URL グループを作成し、1 つ以上の URL グループを要求キューに関連付ける必要があります。アプリケーションは、Property パラメーターで必要な構成を使用して HttpSetRequestQueueProperty を呼び出して要求キューを構成します。 URL グループの作成と構成の詳細については、「 HttpCreateUrlGroup 」および 「HttpSetUrlGroupProperty」を参照してください。

セキュリティ属性は、要求キューが作成されたときにのみ pSecurityAttributes パラメーターで指定できます。要求キューを作成するアプリケーションのみが、要求キューハンドルにAccess Control Lists (ACL) を設定して、プロセス (作成者アプリケーション以外) が要求を開き、要求を受信し、要求キューハンドルで応答を送信できるようにします。既定では、ACL でアクセス許可が付与されていない限り、アプリケーションは要求キューを開くことはできません。

作成者プロセスでは、必要に応じて HTTP_CREATE_REQUEST_QUEUE_FLAG_CONTROLLER フラグを使用して、http 要求を受信しないことを示すことができます。

HttpCreateRequestQueue を使用すると、アプリケーションは HTTP_CREATE_REQUEST_QUEUE_FLAG_OPEN_EXISTING フラグを使用して既存の要求キューを開き、要求キューへのハンドルを取得できます。コントローラー以外のアプリケーションでは、このハンドルを使用して HTTP I/O 操作を実行できます。 HttpSetRequestQueueProperty を呼び出すことで、要求キューを作成するアプリケーションのみがプロパティを設定できます。

HttpCreateRequestQueue によって作成された要求キューへのハンドルは、アプリケーションが終了する前、またはセッションが不要になったときに HttpCloseRequestQueue を呼び出して閉じる必要があります。

アプリケーションは、HttpCreateRequestQueue を呼び出す前に HttpInitialize を呼び出す必要があります。

要件

要件	値
サポートされている最小のクライアント	Windows Vista [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows Server 2008 [デスクトップアプリのみ]
対象プラットフォーム	Windows
ヘッダー	http.h
Library	Httpapi.lib
[DLL]	Httpapi.dll