ホーム › Networking.WinInet › HttpOpenRequestA

HttpOpenRequestA

関数

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

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

シグネチャ

// WININET.dll  (ANSI / -A)
#include <windows.h>

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

パラメーター

名前型方向説明

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

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

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

lpszVersion

LPCSTR

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 LPCSTR inoptional リクエスト内の URL(lpszObjectName)の取得元ドキュメントの URL を指定する null 終端文字列へのポインターです。このパラメーターが NULL の場合、リファラーは指定されません。

lplpszAcceptTypes

LPCSTR*

inoptional

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

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

配列を NULL ポインターで正しく終端しないとクラッシュが発生します。

このパラメーターが NULL の場合、クライアントはどのタイプも受け入れません。サーバーは一般に、受け入れタイプが指定されていないことを、クライアントが "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 リクエストハンドルを作成します。(ANSI)

戻り値

成功した場合は 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 パラメーターがゼロ(INTERNET_NO_CALLBACK)の場合、リクエストハンドルに対して InternetSetStatusCallback で設定したコールバック関数は呼び出されませんが、呼び出し自体は非同期モードで実行されます。

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

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

メモ

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

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

各言語での呼び出し定義

// WININET.dll  (ANSI / -A)
#include <windows.h>

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

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

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

' hConnect : void*
' lpszVerb : LPCSTR optional
' lpszObjectName : LPCSTR optional
' lpszVersion : LPCSTR optional
' lpszReferrer : LPCSTR optional
' lplpszAcceptTypes : LPCSTR* optional
' dwFlags : DWORD
' dwContext : UINT_PTR optional
Declare PtrSafe Function HttpOpenRequestA Lib "wininet" ( _
    ByVal hConnect As LongPtr, _
    ByVal lpszVerb As String, _
    ByVal lpszObjectName As String, _
    ByVal lpszVersion As String, _
    ByVal lpszReferrer As String, _
    ByVal lplpszAcceptTypes As LongPtr, _
    ByVal dwFlags As Long, _
    ByVal dwContext As LongPtr) As LongPtr
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

HttpOpenRequestA = ctypes.windll.wininet.HttpOpenRequestA
HttpOpenRequestA.restype = ctypes.c_void_p
HttpOpenRequestA.argtypes = [
    ctypes.POINTER(None),  # hConnect : void*
    wintypes.LPCSTR,  # lpszVerb : LPCSTR optional
    wintypes.LPCSTR,  # lpszObjectName : LPCSTR optional
    wintypes.LPCSTR,  # lpszVersion : LPCSTR optional
    wintypes.LPCSTR,  # lpszReferrer : LPCSTR optional
    ctypes.c_void_p,  # lplpszAcceptTypes : LPCSTR* 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')
HttpOpenRequestA = Fiddle::Function.new(
  lib['HttpOpenRequestA'],
  [
    Fiddle::TYPE_VOIDP,  # hConnect : void*
    Fiddle::TYPE_VOIDP,  # lpszVerb : LPCSTR optional
    Fiddle::TYPE_VOIDP,  # lpszObjectName : LPCSTR optional
    Fiddle::TYPE_VOIDP,  # lpszVersion : LPCSTR optional
    Fiddle::TYPE_VOIDP,  # lpszReferrer : LPCSTR optional
    Fiddle::TYPE_VOIDP,  # lplpszAcceptTypes : LPCSTR* optional
    -Fiddle::TYPE_INT,  # dwFlags : DWORD
    Fiddle::TYPE_UINTPTR_T,  # dwContext : UINT_PTR optional
  ],
  Fiddle::TYPE_VOIDP)

#[link(name = "wininet")]
extern "system" {
    fn HttpOpenRequestA(
        hConnect: *mut (),  // void*
        lpszVerb: *const u8,  // LPCSTR optional
        lpszObjectName: *const u8,  // LPCSTR optional
        lpszVersion: *const u8,  // LPCSTR optional
        lpszReferrer: *const u8,  // LPCSTR optional
        lplpszAcceptTypes: *const *const u8,  // LPCSTR* 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.Ansi, SetLastError = true)]
public static extern IntPtr HttpOpenRequestA(IntPtr hConnect, [MarshalAs(UnmanagedType.LPStr)] string lpszVerb, [MarshalAs(UnmanagedType.LPStr)] string lpszObjectName, [MarshalAs(UnmanagedType.LPStr)] string lpszVersion, [MarshalAs(UnmanagedType.LPStr)] string lpszReferrer, IntPtr lplpszAcceptTypes, uint dwFlags, UIntPtr dwContext);
"@
$api = Add-Type -MemberDefinition $sig -Name 'WININET_HttpOpenRequestA' -Namespace Win32 -PassThru
# $api::HttpOpenRequestA(hConnect, lpszVerb, lpszObjectName, lpszVersion, lpszReferrer, lplpszAcceptTypes, dwFlags, dwContext)

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

出力引数:

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