ホーム › Networking.WinInet › HttpOpenRequestW

HttpOpenRequestW

関数

HTTPリクエストハンドルを作成する(Unicode版)。

DLLWININET.dll文字セットUnicode (-W)呼出規約winapiSetLastErrorあり対応OSWindows 2000 以降

シグネチャ

// WININET.dll  (Unicode / -W)
#include <windows.h>

void* HttpOpenRequestW(
    void* hConnect,
    LPCWSTR lpszVerb,   // optional
    LPCWSTR lpszObjectName,   // optional
    LPCWSTR lpszVersion,   // optional
    LPCWSTR lpszReferrer,   // optional
    LPCWSTR* lplpszAcceptTypes,   // optional
    DWORD dwFlags,
    UINT_PTR dwContext   // optional
);

パラメーター

名前型方向説明

hConnect void* in InternetConnect が返した HTTP セッションへのハンドルです。

lpszVerb LPCWSTR inoptional リクエストで使用する HTTP 動詞を含む null で終わる文字列へのポインターです。このパラメーターが NULL の場合、関数は HTTP 動詞として GET を使用します。

lpszObjectName LPCWSTR inoptional 指定された HTTP 動詞の対象オブジェクトの名前を含む null で終わる文字列へのポインターです。通常はファイル名、実行可能モジュール、または検索指定子です。

lpszVersion

LPCWSTR

inoptional

リクエストで使用する HTTP バージョンを含む null で終わる文字列へのポインターです。Internet Explorer の設定は、このパラメーターで指定された値を上書きします。

このパラメーターが NULL の場合、関数は Internet Explorer の設定値に応じて HTTP バージョン 1.1 または 1.0 を使用します。

値	意味
HTTP/1.0	HTTP バージョン 1.0
HTTP/1.1	HTTP バージョン 1.1

lpszReferrer LPCWSTR inoptional リクエスト内の URL (lpszObjectName) を取得した元のドキュメントの URL を指定する null で終わる文字列へのポインターです。このパラメーターが NULL の場合、リファラーは指定されません。

lplpszAcceptTypes

LPCWSTR*

inoptional

クライアントが受け入れるメディアタイプを示す null で終わる文字列の配列へのポインターです。以下に例を示します。

PCTSTR rgpszAcceptTypes[] = {_T("text/*"), NULL};

配列を NULL ポインターで適切に終端しないと、クラッシュの原因になります。

このパラメーターが NULL の場合、クライアントはどのタイプも受け入れません。サーバーは一般に、accept タイプが指定されていないことを、クライアントが "text/*" タイプのドキュメント (つまりテキストドキュメントのみで、画像やその他のバイナリファイルは含まない) のみを受け入れると解釈します。!--For more information and a list of valid media types, see ftp://ftp.isi.edu/in-notes/iana/assignments/media-types/media-types. -->

dwFlags

DWORD

インターネットオプションです。このパラメーターには次のいずれかの値を指定できます。

値	意味
INTERNET_FLAG_CACHE_IF_NET_FAIL	リソースに対するネットワークリクエストが ERROR_INTERNET_CONNECTION_RESET (サーバーとの接続がリセットされた) または ERROR_INTERNET_CANNOT_CONNECT (サーバーへの接続試行が失敗した) により失敗した場合に、キャッシュからリソースを返します。
INTERNET_FLAG_HYPERLINK	ネットワークから項目を再読み込みするかどうかを判断する際に、サーバーから Expires 時刻も LastModified 時刻も返されなかった場合に、強制的に再読み込みを行います。
INTERNET_FLAG_IGNORE_CERT_CN_INVALID	サーバーから返された SSL/PCT ベースの証明書を、リクエストで指定されたホスト名と照合するチェックを無効にします。WinINet 関数は、ホスト名の一致と単純なワイルドカードルールを比較する簡単なチェックを証明書に対して行います。
INTERNET_FLAG_IGNORE_CERT_DATE_INVALID	SSL/PCT ベースの証明書の有効期日の妥当性チェックを無効にします。
INTERNET_FLAG_IGNORE_REDIRECT_TO_HTTP	この特殊な種類のリダイレクトの検出を無効にします。このフラグを使用すると、WinINet 関数は HTTPS から HTTP URL へのリダイレクトを透過的に許可します。
INTERNET_FLAG_IGNORE_REDIRECT_TO_HTTPS	この特殊な種類のリダイレクトの検出を無効にします。このフラグを使用すると、WinINet 関数は HTTP から HTTPS URL へのリダイレクトを透過的に許可します。
INTERNET_FLAG_KEEP_CONNECTION	接続で利用可能であれば keep-alive セマンティクスを使用します。このフラグは Microsoft Network (MSN)、NT LAN Manager (NTLM)、およびその他の種類の認証に必要です。
INTERNET_FLAG_NEED_FILE	ファイルをキャッシュできない場合に、一時ファイルを作成させます。
INTERNET_FLAG_NO_AUTH	自動的な認証を試行しません。
INTERNET_FLAG_NO_AUTO_REDIRECT	HttpSendRequest でリダイレクトを自動的に処理しません。
INTERNET_FLAG_NO_CACHE_WRITE	返されたエンティティをキャッシュに追加しません。
INTERNET_FLAG_NO_COOKIES	リクエストに Cookie ヘッダーを自動的に追加せず、返された Cookie を Cookie データベースに自動的に追加しません。
INTERNET_FLAG_NO_UI	Cookie ダイアログボックスを無効にします。
INTERNET_FLAG_PRAGMA_NOCACHE	プロキシにキャッシュされたコピーが存在する場合でも、リクエストをオリジンサーバーで解決させます。
INTERNET_FLAG_RELOAD	要求されたファイル、オブジェクト、またはディレクトリ一覧を、キャッシュからではなくオリジンサーバーから強制的にダウンロードします。
INTERNET_FLAG_RESYNCHRONIZE	前回ダウンロードした時点以降にリソースが変更されている場合に、HTTP リソースを再読み込みします。すべての FTP リソースは再読み込みされます。 Windows XP および Windows Server 2003 R2 以前: Gopher リソースも再読み込みされます。
INTERNET_FLAG_SECURE	セキュアなトランザクションセマンティクスを使用します。これは Secure Sockets Layer/Private Communications Technology (SSL/PCT) の使用を意味し、HTTP リクエストでのみ有効です。

dwContext UINT_PTR inoptional この操作を任意のアプリケーションデータと関連付ける、アプリケーション定義の値を含む変数へのポインターです。

戻り値の型: void*

公式ドキュメント

HTTP リクエストハンドルを作成します。(Unicode)

戻り値

成功した場合は HTTP リクエストハンドルを返し、それ以外の場合は NULL を返します。拡張エラー情報を取得するには、GetLastError を呼び出します。

解説(Remarks)

HttpOpenRequest 関数は新しい HTTP リクエストハンドルを作成し、指定されたパラメーターをそのハンドルに格納します。HTTP リクエストハンドルは、HTTP サーバーに送信するリクエストを保持し、リクエストの一部として送信されるすべての RFC822/MIME/HTTP ヘッダーを含みます。

"GET" または "POST" 以外の動詞が指定された場合、HttpOpenRequest はそのリクエストに対して INTERNET_FLAG_NO_CACHE_WRITE と INTERNET_FLAG_RELOAD を自動的に設定します。

Microsoft Internet Explorer 5 以降では、lpszVerb が "HEAD" に設定されている場合、HTTP/1.1 サーバーからの応答で Content-Length ヘッダーは無視されます。

Windows 7、Windows Server 2008 R2 以降では、lpszVersion パラメーターは Internet Explorer の設定によって上書きされます。EnableHttp1_1 は HKLM\Software\Microsoft\InternetExplorer\AdvacnedOptions\HTTP\GENABLE 配下のレジストリ値で、システムの Internet Explorer で設定されたインターネットオプションによって制御されます。EnableHttp1_1 値の既定値は 1 です。EnableHttp1_1 が 1 に設定されている場合、HttpOpenRequest 関数は 1.1 未満の HTTP バージョンを HTTP バージョン 1.1 にアップグレードします。

呼び出し側アプリケーションが HttpOpenRequest によって返された HINTERNET ハンドルの使用を終えた後は、InternetCloseHandle 関数を使用してハンドルを閉じる必要があります。

注意リクエストが非同期モードで送信され (InternetOpen の dwFlags パラメーターに INTERNET_FLAG_ASYNC を指定)、かつ dwContext パラメーターが 0 (INTERNET_NO_CALLBACK) の場合、リクエストハンドルに対して InternetSetStatusCallback で設定したコールバック関数は呼び出されませんが、呼び出しは引き続き非同期モードで実行されます。

WinINet API の他のすべての側面と同様に、この関数は DllMain やグローバルオブジェクトのコンストラクター・デストラクター内から安全に呼び出すことはできません。

注意 WinINet はサーバー実装をサポートしていません。また、サービスから使用すべきではありません。サーバー実装やサービスには Microsoft Windows HTTP Services (WinHTTP) を使用してください。

メモ

wininet.h ヘッダーは HttpOpenRequest を、UNICODE プリプロセッサ定数の定義に基づいてこの関数の ANSI 版または Unicode 版を自動的に選択するエイリアスとして定義しています。エンコーディング非依存のエイリアスの使用と、エンコーディング非依存でないコードを混在させると、コンパイルエラーや実行時エラーを引き起こす不一致が生じる可能性があります。詳細については、関数プロトタイプの規則を参照してください。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// WININET.dll  (Unicode / -W)
#include <windows.h>

void* HttpOpenRequestW(
    void* hConnect,
    LPCWSTR lpszVerb,   // optional
    LPCWSTR lpszObjectName,   // optional
    LPCWSTR lpszVersion,   // optional
    LPCWSTR lpszReferrer,   // optional
    LPCWSTR* lplpszAcceptTypes,   // optional
    DWORD dwFlags,
    UINT_PTR dwContext   // optional
);

[DllImport("WININET.dll", CharSet = CharSet.Unicode, SetLastError = true, ExactSpelling = true)]
static extern IntPtr HttpOpenRequestW(
    IntPtr hConnect,   // void*
    [MarshalAs(UnmanagedType.LPWStr)] string lpszVerb,   // LPCWSTR optional
    [MarshalAs(UnmanagedType.LPWStr)] string lpszObjectName,   // LPCWSTR optional
    [MarshalAs(UnmanagedType.LPWStr)] string lpszVersion,   // LPCWSTR optional
    [MarshalAs(UnmanagedType.LPWStr)] string lpszReferrer,   // LPCWSTR optional
    IntPtr lplpszAcceptTypes,   // LPCWSTR* optional
    uint dwFlags,   // DWORD
    UIntPtr dwContext   // UINT_PTR optional
);

<DllImport("WININET.dll", CharSet:=CharSet.Unicode, SetLastError:=True, ExactSpelling:=True)>
Public Shared Function HttpOpenRequestW(
    hConnect As IntPtr,   ' void*
    <MarshalAs(UnmanagedType.LPWStr)> lpszVerb As String,   ' LPCWSTR optional
    <MarshalAs(UnmanagedType.LPWStr)> lpszObjectName As String,   ' LPCWSTR optional
    <MarshalAs(UnmanagedType.LPWStr)> lpszVersion As String,   ' LPCWSTR optional
    <MarshalAs(UnmanagedType.LPWStr)> lpszReferrer As String,   ' LPCWSTR optional
    lplpszAcceptTypes As IntPtr,   ' LPCWSTR* optional
    dwFlags As UInteger,   ' DWORD
    dwContext As UIntPtr   ' UINT_PTR optional
) As IntPtr
End Function

' hConnect : void*
' lpszVerb : LPCWSTR optional
' lpszObjectName : LPCWSTR optional
' lpszVersion : LPCWSTR optional
' lpszReferrer : LPCWSTR optional
' lplpszAcceptTypes : LPCWSTR* optional
' dwFlags : DWORD
' dwContext : UINT_PTR optional
Declare PtrSafe Function HttpOpenRequestW Lib "wininet" ( _
    ByVal hConnect As LongPtr, _
    ByVal lpszVerb As LongPtr, _
    ByVal lpszObjectName As LongPtr, _
    ByVal lpszVersion As LongPtr, _
    ByVal lpszReferrer As LongPtr, _
    ByVal lplpszAcceptTypes As LongPtr, _
    ByVal dwFlags As Long, _
    ByVal dwContext As LongPtr) As LongPtr
' Unicode(W): 文字列は ByVal As LongPtr とし StrPtr(unicodeStr) を渡す
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

HttpOpenRequestW = ctypes.windll.wininet.HttpOpenRequestW
HttpOpenRequestW.restype = ctypes.c_void_p
HttpOpenRequestW.argtypes = [
    ctypes.POINTER(None),  # hConnect : void*
    wintypes.LPCWSTR,  # lpszVerb : LPCWSTR optional
    wintypes.LPCWSTR,  # lpszObjectName : LPCWSTR optional
    wintypes.LPCWSTR,  # lpszVersion : LPCWSTR optional
    wintypes.LPCWSTR,  # lpszReferrer : LPCWSTR optional
    ctypes.c_void_p,  # lplpszAcceptTypes : LPCWSTR* optional
    wintypes.DWORD,  # dwFlags : DWORD
    ctypes.c_size_t,  # dwContext : UINT_PTR optional
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('WININET.dll')
HttpOpenRequestW = Fiddle::Function.new(
  lib['HttpOpenRequestW'],
  [
    Fiddle::TYPE_VOIDP,  # hConnect : void*
    Fiddle::TYPE_VOIDP,  # lpszVerb : LPCWSTR optional
    Fiddle::TYPE_VOIDP,  # lpszObjectName : LPCWSTR optional
    Fiddle::TYPE_VOIDP,  # lpszVersion : LPCWSTR optional
    Fiddle::TYPE_VOIDP,  # lpszReferrer : LPCWSTR optional
    Fiddle::TYPE_VOIDP,  # lplpszAcceptTypes : LPCWSTR* optional
    -Fiddle::TYPE_INT,  # dwFlags : DWORD
    Fiddle::TYPE_UINTPTR_T,  # dwContext : UINT_PTR optional
  ],
  Fiddle::TYPE_VOIDP)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"

#[link(name = "wininet")]
extern "system" {
    fn HttpOpenRequestW(
        hConnect: *mut (),  // void*
        lpszVerb: *const u16,  // LPCWSTR optional
        lpszObjectName: *const u16,  // LPCWSTR optional
        lpszVersion: *const u16,  // LPCWSTR optional
        lpszReferrer: *const u16,  // LPCWSTR optional
        lplpszAcceptTypes: *const *const u16,  // LPCWSTR* optional
        dwFlags: u32,  // DWORD
        dwContext: usize  // UINT_PTR optional
    ) -> *mut ();
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("WININET.dll", CharSet = CharSet.Unicode, SetLastError = true)]
public static extern IntPtr HttpOpenRequestW(IntPtr hConnect, [MarshalAs(UnmanagedType.LPWStr)] string lpszVerb, [MarshalAs(UnmanagedType.LPWStr)] string lpszObjectName, [MarshalAs(UnmanagedType.LPWStr)] string lpszVersion, [MarshalAs(UnmanagedType.LPWStr)] string lpszReferrer, IntPtr lplpszAcceptTypes, uint dwFlags, UIntPtr dwContext);
"@
$api = Add-Type -MemberDefinition $sig -Name 'WININET_HttpOpenRequestW' -Namespace Win32 -PassThru
# $api::HttpOpenRequestW(hConnect, lpszVerb, lpszObjectName, lpszVersion, lpszReferrer, lplpszAcceptTypes, dwFlags, dwContext)

#uselib "WININET.dll"
#func global HttpOpenRequestW "HttpOpenRequestW" wptr, wptr, wptr, wptr, wptr, wptr, wptr, wptr
; HttpOpenRequestW hConnect, lpszVerb, lpszObjectName, lpszVersion, lpszReferrer, varptr(lplpszAcceptTypes), dwFlags, dwContext   ; 戻り値は stat
; hConnect : void* -> "wptr"
; lpszVerb : LPCWSTR optional -> "wptr"
; lpszObjectName : LPCWSTR optional -> "wptr"
; lpszVersion : LPCWSTR optional -> "wptr"
; lpszReferrer : LPCWSTR optional -> "wptr"
; lplpszAcceptTypes : LPCWSTR* optional -> "wptr"
; dwFlags : DWORD -> "wptr"
; dwContext : UINT_PTR optional -> "wptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "WININET.dll"
#cfunc global HttpOpenRequestW "HttpOpenRequestW" sptr, wstr, wstr, wstr, wstr, var, int, sptr
; res = HttpOpenRequestW(hConnect, lpszVerb, lpszObjectName, lpszVersion, lpszReferrer, lplpszAcceptTypes, dwFlags, dwContext)
; hConnect : void* -> "sptr"
; lpszVerb : LPCWSTR optional -> "wstr"
; lpszObjectName : LPCWSTR optional -> "wstr"
; lpszVersion : LPCWSTR optional -> "wstr"
; lpszReferrer : LPCWSTR optional -> "wstr"
; lplpszAcceptTypes : LPCWSTR* optional -> "var"
; dwFlags : DWORD -> "int"
; dwContext : UINT_PTR optional -> "sptr"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "WININET.dll"
#cfunc global HttpOpenRequestW "HttpOpenRequestW" sptr, wstr, wstr, wstr, wstr, sptr, int, sptr
; res = HttpOpenRequestW(hConnect, lpszVerb, lpszObjectName, lpszVersion, lpszReferrer, varptr(lplpszAcceptTypes), dwFlags, dwContext)
; hConnect : void* -> "sptr"
; lpszVerb : LPCWSTR optional -> "wstr"
; lpszObjectName : LPCWSTR optional -> "wstr"
; lpszVersion : LPCWSTR optional -> "wstr"
; lpszReferrer : LPCWSTR optional -> "wstr"
; lplpszAcceptTypes : LPCWSTR* optional -> "sptr"
; dwFlags : DWORD -> "int"
; dwContext : UINT_PTR optional -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。