ホーム › Networking.WinHttp › WinHttpCrackUrl

WinHttpCrackUrl

関数

URLを構成要素に分解して解析する。

DLLWINHTTP.dll呼出規約winapiSetLastErrorあり対応OSWindows XP 以降

シグネチャ

// WINHTTP.dll
#include <windows.h>

BOOL WinHttpCrackUrl(
    LPCWSTR pwszUrl,
    DWORD dwUrlLength,
    DWORD dwFlags,
    URL_COMPONENTS* lpUrlComponents
);

パラメーター

名前

型

方向

説明

pwszUrl

LPCWSTR

分解対象の正規化された URL を格納する文字列へのポインター。WinHttpCrackUrl は、分解を試みる前にこの URL の妥当性や形式の正しさを確認しません。

dwUrlLength

DWORD

pwszUrl 文字列の長さ(文字数)。 dwUrlLength に 0 を指定した場合、 WinHttpCrackUrl は pwszUrl 文字列が null で終端されているものとみなし、その前提に基づいて pwszUrl 文字列の長さを判定します。

dwFlags

DWORD

動作を制御するフラグ。このパラメーターには、以下のフラグの 1 つ以上を組み合わせて指定できます(複数の値をビット単位の OR で結合できます)。または、特別な操作を行わない場合は 0 を指定できます。

値	意味
ICU_DECODE	「エスケープエンコード」された文字(%xx)を、エスケープされていない形式に変換します。これは UTF-8 などの他のエンコードはデコードしません。この機能は、ユーザーが構成要素をコピーするためのバッファーを URL_COMPONENTS 構造体に用意している場合にのみ使用できます。
ICU_ESCAPE	特定の文字をエスケープシーケンス(%xx)に変換します。エスケープされる文字は、非 ASCII 文字、または HTTP リクエストで表現するためにエスケープが必要な ASCII 文字です。この機能は、ユーザーが構成要素をコピーするためのバッファーを URL_COMPONENTS 構造体に用意している場合にのみ使用できます。
ICU_REJECT_USERPWD	埋め込まれた資格情報(ユーザー名、パスワード、またはその両方)を含む URL を入力として拒否します。無効な URL が原因で関数が失敗した場合、以降の GetLastError の呼び出しは ERROR_WINHTTP_INVALID_URL を返します。

lpUrlComponents

URL_COMPONENTS*

inout

URL の構成要素を受け取る URL_COMPONENTS 構造体へのポインター。

戻り値の型: BOOL

公式ドキュメント

WinHttpCrackUrl 関数は、URL をホスト名やパスなどの構成要素に分解します。

戻り値

関数が成功した場合は TRUE を、それ以外の場合は FALSE を返します。拡張エラー情報を取得するには、 GetLastError を呼び出します。返されるエラーコードには次のものがあります。

エラーコード	説明
ERROR_WINHTTP_INTERNAL_ERROR	内部エラーが発生しました。
ERROR_WINHTTP_INVALID_URL	URL が無効です。
ERROR_WINHTTP_UNRECOGNIZED_SCHEME	URL のスキームを認識できなかったか、サポートされていません。
ERROR_NOT_ENOUGH_MEMORY	要求された操作を完了するのに十分なメモリがありませんでした。(Windows エラーコード)

解説(Remarks)

WinHTTP が非同期モードで使用されている場合(つまり WinHttpOpen で WINHTTP_FLAG_ASYNC が設定されている場合)でも、この関数は同期的に動作します。戻り値は成功または失敗を示します。拡張エラー情報を取得するには、 GetLastError を呼び出します。

必要な構成要素は、 URL_COMPONENTS 構造体のメンバーによって指定します。各構成要素は値へのポインターを持ち、格納された値の長さを保持するメンバーを持ちます。ある構成要素の値と長さが両方とも 0 の場合、その構成要素は返されません。構成要素の値へのポインターが NULL で、対応する長さメンバーの値が 0 以外の場合、 pwszUrl 文字列内の対応する構成要素の先頭文字のアドレスがポインターに格納され、構成要素の長さが長さメンバーに格納されます。

ポインターがユーザー指定のバッファーのアドレスを保持している場合、長さメンバーにはそのバッファーのサイズを格納する必要があります。 WinHttpCrackUrl 関数は構成要素をバッファーにコピーし、長さメンバーにはコピーされた構成要素の長さ(末尾の文字列終端子の分として 1 を引いた値)が設定されます。ユーザー指定のバッファーが十分に大きくない場合、WinHttpCrackUrl は FALSE を返し、GetLastError は ERROR_INSUFFICIENT_BUFFER を返します。

lpUrlComponents で lpszExtraInfo が設定されていないか dwExtraInfoLength が 0 のままの場合、lpszUrlPath が設定されていれば、URL のクエリおよび/またはフラグメントの構成要素がそのフィールドに含まれます。

WinHttpCrackUrl が正しく動作するためには、 URL_COMPONENTS 構造体のサイズをその構造体の dwStructSize メンバーに格納する必要があります。

pwszUrl に渡された URL のインターネットプロトコルが HTTP または HTTPS でない場合、 WinHttpCrackUrl は FALSE を返し、 GetLastError は ERROR_WINHTTP_UNRECOGNIZED_SCHEME を示します。

WinHttpCrackUrl は、分解を試みる前に URL の妥当性や形式を確認しません。そのため、""http://server?Bad=URL"" のような文字列が渡された場合、この関数は誤った結果を返します。

注意 Windows XP および Windows 2000 については、WinHttp スタートページの Run-Time Requirements セクションを参照してください。

例

この例では、URL を構成要素に分解し、構成要素を更新してから URL を再構築する方法を示します。

    URL_COMPONENTS urlComp;
    LPCWSTR pwszUrl1 = 
      L"http://search.msn.com/results.asp?RS=CHECKED&FORM=MSNH&v=1&q=wininet";
    DWORD dwUrlLen = 0;

    // Initialize the URL_COMPONENTS structure.
    ZeroMemory(&urlComp, sizeof(urlComp));
    urlComp.dwStructSize = sizeof(urlComp);

    // Set required component lengths to non-zero 
    // so that they are cracked.
    urlComp.dwSchemeLength    = (DWORD)-1;
    urlComp.dwHostNameLength  = (DWORD)-1;
    urlComp.dwUrlPathLength   = (DWORD)-1;
    urlComp.dwExtraInfoLength = (DWORD)-1;

    // Crack the URL.
    if (!WinHttpCrackUrl( pwszUrl1, (DWORD)wcslen(pwszUrl1), 0, &urlComp))
    {
        printf("Error %u in WinHttpCrackUrl.\n", GetLastError());
    }
    else
    {
        // Change the search information.  
        // New info is the same length.
        urlComp.lpszExtraInfo = L"?RS=CHECKED&FORM=MSNH&v=1&q=winhttp";

        // Obtain the size of the new URL and allocate memory.
        WinHttpCreateUrl( &urlComp, 0, NULL, &dwUrlLen);
        LPWSTR pwszUrl2 = new WCHAR[dwUrlLen];

        // Create a new URL.
        if(!WinHttpCreateUrl( &urlComp, 0, pwszUrl2, &dwUrlLen))
        {
            printf("Error %u in WinHttpCreateUrl.\n", GetLastError());
        }
        else
        {
            // Show both URLs.
            printf("Old URL:  %S\nNew URL:  %S\n", pwszUrl1, pwszUrl2);
        }

        // Free allocated memory.
        delete [] pwszUrl2;
    }

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

各言語での呼び出し定義

// WINHTTP.dll
#include <windows.h>

BOOL WinHttpCrackUrl(
    LPCWSTR pwszUrl,
    DWORD dwUrlLength,
    DWORD dwFlags,
    URL_COMPONENTS* lpUrlComponents
);

[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("WINHTTP.dll", SetLastError = true, ExactSpelling = true)]
static extern bool WinHttpCrackUrl(
    [MarshalAs(UnmanagedType.LPWStr)] string pwszUrl,   // LPCWSTR
    uint dwUrlLength,   // DWORD
    uint dwFlags,   // DWORD
    IntPtr lpUrlComponents   // URL_COMPONENTS* in/out
);

<DllImport("WINHTTP.dll", SetLastError:=True, ExactSpelling:=True)>
Public Shared Function WinHttpCrackUrl(
    <MarshalAs(UnmanagedType.LPWStr)> pwszUrl As String,   ' LPCWSTR
    dwUrlLength As UInteger,   ' DWORD
    dwFlags As UInteger,   ' DWORD
    lpUrlComponents As IntPtr   ' URL_COMPONENTS* in/out
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function

' pwszUrl : LPCWSTR
' dwUrlLength : DWORD
' dwFlags : DWORD
' lpUrlComponents : URL_COMPONENTS* in/out
Declare PtrSafe Function WinHttpCrackUrl Lib "winhttp" ( _
    ByVal pwszUrl As LongPtr, _
    ByVal dwUrlLength As Long, _
    ByVal dwFlags As Long, _
    ByVal lpUrlComponents As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

WinHttpCrackUrl = ctypes.windll.winhttp.WinHttpCrackUrl
WinHttpCrackUrl.restype = wintypes.BOOL
WinHttpCrackUrl.argtypes = [
    wintypes.LPCWSTR,  # pwszUrl : LPCWSTR
    wintypes.DWORD,  # dwUrlLength : DWORD
    wintypes.DWORD,  # dwFlags : DWORD
    ctypes.c_void_p,  # lpUrlComponents : URL_COMPONENTS* in/out
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('WINHTTP.dll')
WinHttpCrackUrl = Fiddle::Function.new(
  lib['WinHttpCrackUrl'],
  [
    Fiddle::TYPE_VOIDP,  # pwszUrl : LPCWSTR
    -Fiddle::TYPE_INT,  # dwUrlLength : DWORD
    -Fiddle::TYPE_INT,  # dwFlags : DWORD
    Fiddle::TYPE_VOIDP,  # lpUrlComponents : URL_COMPONENTS* in/out
  ],
  Fiddle::TYPE_INT)

#[link(name = "winhttp")]
extern "system" {
    fn WinHttpCrackUrl(
        pwszUrl: *const u16,  // LPCWSTR
        dwUrlLength: u32,  // DWORD
        dwFlags: u32,  // DWORD
        lpUrlComponents: *mut URL_COMPONENTS  // URL_COMPONENTS* in/out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("WINHTTP.dll", SetLastError = true)]
public static extern bool WinHttpCrackUrl([MarshalAs(UnmanagedType.LPWStr)] string pwszUrl, uint dwUrlLength, uint dwFlags, IntPtr lpUrlComponents);
"@
$api = Add-Type -MemberDefinition $sig -Name 'WINHTTP_WinHttpCrackUrl' -Namespace Win32 -PassThru
# $api::WinHttpCrackUrl(pwszUrl, dwUrlLength, dwFlags, lpUrlComponents)

#uselib "WINHTTP.dll"
#func global WinHttpCrackUrl "WinHttpCrackUrl" sptr, sptr, sptr, sptr
; WinHttpCrackUrl pwszUrl, dwUrlLength, dwFlags, varptr(lpUrlComponents)   ; 戻り値は stat
; pwszUrl : LPCWSTR -> "sptr"
; dwUrlLength : DWORD -> "sptr"
; dwFlags : DWORD -> "sptr"
; lpUrlComponents : URL_COMPONENTS* in/out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "WINHTTP.dll"
#cfunc global WinHttpCrackUrl "WinHttpCrackUrl" wstr, int, int, var
; res = WinHttpCrackUrl(pwszUrl, dwUrlLength, dwFlags, lpUrlComponents)
; pwszUrl : LPCWSTR -> "wstr"
; dwUrlLength : DWORD -> "int"
; dwFlags : DWORD -> "int"
; lpUrlComponents : URL_COMPONENTS* in/out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "WINHTTP.dll"
#cfunc global WinHttpCrackUrl "WinHttpCrackUrl" wstr, int, int, sptr
; res = WinHttpCrackUrl(pwszUrl, dwUrlLength, dwFlags, varptr(lpUrlComponents))
; pwszUrl : LPCWSTR -> "wstr"
; dwUrlLength : DWORD -> "int"
; dwFlags : DWORD -> "int"
; lpUrlComponents : URL_COMPONENTS* in/out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。