GetStringTypeExW

関数

ロケール指定で各文字の文字種情報を取得する。

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

シグネチャ

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

BOOL GetStringTypeExW(
    DWORD Locale,
    DWORD dwInfoType,
    LPCWSTR lpSrcStr,
    INT cchSrc,
    WORD* lpCharType
);

パラメーター

名前	型	方向	説明
Locale	DWORD	in	ロケールを指定するロケール識別子です。この値は ANSI コードページを一意に定義します。MAKELCID マクロを使用してロケール識別子を作成するか、次の定義済みの値のいずれかを使用できます。 LOCALE_SYSTEM_DEFAULT LOCALE_USER_DEFAULT Windows Vista 以降: 次のカスタムロケール識別子もサポートされます。 LOCALE_CUSTOM_DEFAULT LOCALE_CUSTOM_UI_DEFAULT LOCALE_CUSTOM_UNSPECIFIED
dwInfoType	DWORD	in	取得する文字型情報を指定するフラグです。指定可能なフラグ値については、GetStringTypeW の dwInfoType パラメーターを参照してください。文字型ビットの詳細については、GetStringTypeW の「解説」を参照してください。
lpSrcStr	LPCWSTR	in	文字型を取得する対象の文字列へのポインターです。cchSrc に負の値を設定した場合、この文字列は null で終端されているものとみなされます。
cchSrc	INT	in	lpSrcStr が示す文字列のサイズ(文字数)です。このサイズは、関数の ANSI 版ではバイト数、Unicode 版ではワイド文字数を指します。サイズに終端の null 文字を含めた場合、この関数はその文字についても文字型情報を取得します。アプリケーションがサイズに負の整数を設定した場合、ソース文字列は null で終端されているものとみなされ、null 終端分の 1 文字を加えたサイズが自動的に計算されます。
lpCharType	WORD*	out	16 ビット値の配列へのポインターです。この配列の長さは、ソース文字列内の各文字に対して 1 つの 16 ビット値を受け取るのに十分な大きさである必要があります。cchSrc が負の数でない場合、lpCharType は cchSrc 個の要素を持つワードの配列である必要があります。cchSrc に負の数を設定した場合、lpCharType は lpSrcStr + 1 個の要素を持つワードの配列になります。関数が返ると、この配列にはソース文字列内の各文字に対応する 1 つのワードが格納されます。

戻り値の型: BOOL

公式ドキュメント

指定したソース文字列に含まれる文字の文字型情報を取得します。

戻り値

成功した場合は 0 以外の値を返し、それ以外の場合は 0 を返します。拡張エラー情報を取得するには、アプリケーションは GetLastError を呼び出すことができます。この関数は次のエラーコードのいずれかを返すことがあります。

ERROR_INVALID_FLAGS。フラグに指定された値が無効でした。
ERROR_INVALID_PARAMETER。いずれかのパラメーター値が無効でした。

解説(Remarks)

重要

GetStringTypeEx 関数を誤って使用すると、アプリケーションのセキュリティが損なわれるおそれがあります。バッファーオーバーフローを避けるため、アプリケーションは出力バッファーのサイズを正しく設定する必要があります。セキュリティに関する詳細については、セキュリティに関する考慮事項: Windows ユーザーインターフェイスを参照してください。

近縁の関数である GetStringTypeA や GetStringTypeW とは異なり、この関数は #define UNICODE スイッチの使用によって、適切な ANSI 動作または Unicode 動作を示します。文字型の取得には、この関数を使用することをお勧めします。

文字列関数の使用方法の概要については、Strings を参照してください。

この関数は、指定されたロケールの ANSI コードページを使用して、ソース文字列を ANSI から Unicode に変換します。その後、各 Unicode 文字を解析して文字型情報を取得します。

この関数の ANSI 版は、ソース文字列を Unicode に変換し、対応する GetStringTypeW 関数を呼び出します。そのため、出力バッファー内のワードは、元の ANSI 文字列ではなく、その Unicode 等価物に対応します。ANSI から Unicode への変換では文字列長が変化することがあります。たとえば、ANSI 文字 2 つが 1 つの Unicode 文字にマップされる場合があります。したがって、出力バッファー内のワードと元の ANSI 文字列内の文字との対応は、すべての場合で 1 対 1 になるとは限りません(たとえばマルチバイト文字列の場合)。このため、この関数の ANSI 版は複数文字からなる文字列に対しては用途が限られます。代わりに Unicode 版の関数を使用することをお勧めします。

この関数は、GetStringTypeA と GetStringTypeW のパラメーターの違いによって生じる制限を回避します。このパラメーターの違いのため、アプリケーションは #define UNICODE スイッチを使用しても、GetStringType* 関数の適切な ANSI 版または Unicode 版を自動的に呼び出すことができません。一方、GetStringTypeEx はそのスイッチに対して適切に動作します。そのため、この関数の使用が推奨されます。

この関数の ANSI 版を Unicode 専用のロケール識別子とともに使用した場合、オペレーティングシステムがシステムコードページを使用するため、関数が成功することがあります。ただし、システムコードページで未定義の文字は、文字列内で疑問符(?)として現れます。

lpSrcStr と lpCharType パラメーターの値は同一であってはなりません。同一の場合、関数は ERROR_INVALID_PARAMETER で失敗します。

Locale パラメーターは、文字列を Unicode に変換するためにのみ使用されます。アプリケーションに返される CTYPE* の値とは無関係です。これらの値は Unicode コードポイントのみによって決定され、ロケールによって変化することはありません。たとえば、ギリシャ文字は Locale の値に関わらず C1_ALPHA として指定されます。

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

各言語での呼び出し定義

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

BOOL GetStringTypeExW(
    DWORD Locale,
    DWORD dwInfoType,
    LPCWSTR lpSrcStr,
    INT cchSrc,
    WORD* lpCharType
);

[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("KERNEL32.dll", CharSet = CharSet.Unicode, SetLastError = true, ExactSpelling = true)]
static extern bool GetStringTypeExW(
    uint Locale,   // DWORD
    uint dwInfoType,   // DWORD
    [MarshalAs(UnmanagedType.LPWStr)] string lpSrcStr,   // LPCWSTR
    int cchSrc,   // INT
    out ushort lpCharType   // WORD* out
);

<DllImport("KERNEL32.dll", CharSet:=CharSet.Unicode, SetLastError:=True, ExactSpelling:=True)>
Public Shared Function GetStringTypeExW(
    Locale As UInteger,   ' DWORD
    dwInfoType As UInteger,   ' DWORD
    <MarshalAs(UnmanagedType.LPWStr)> lpSrcStr As String,   ' LPCWSTR
    cchSrc As Integer,   ' INT
    <Out> ByRef lpCharType As UShort   ' WORD* out
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function

' Locale : DWORD
' dwInfoType : DWORD
' lpSrcStr : LPCWSTR
' cchSrc : INT
' lpCharType : WORD* out
Declare PtrSafe Function GetStringTypeExW Lib "kernel32" ( _
    ByVal Locale As Long, _
    ByVal dwInfoType As Long, _
    ByVal lpSrcStr As LongPtr, _
    ByVal cchSrc As Long, _
    ByRef lpCharType As Integer) As Long
' 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

GetStringTypeExW = ctypes.windll.kernel32.GetStringTypeExW
GetStringTypeExW.restype = wintypes.BOOL
GetStringTypeExW.argtypes = [
    wintypes.DWORD,  # Locale : DWORD
    wintypes.DWORD,  # dwInfoType : DWORD
    wintypes.LPCWSTR,  # lpSrcStr : LPCWSTR
    ctypes.c_int,  # cchSrc : INT
    ctypes.POINTER(ctypes.c_ushort),  # lpCharType : WORD* out
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('KERNEL32.dll')
GetStringTypeExW = Fiddle::Function.new(
  lib['GetStringTypeExW'],
  [
    -Fiddle::TYPE_INT,  # Locale : DWORD
    -Fiddle::TYPE_INT,  # dwInfoType : DWORD
    Fiddle::TYPE_VOIDP,  # lpSrcStr : LPCWSTR
    Fiddle::TYPE_INT,  # cchSrc : INT
    Fiddle::TYPE_VOIDP,  # lpCharType : WORD* out
  ],
  Fiddle::TYPE_INT)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"

#[link(name = "kernel32")]
extern "system" {
    fn GetStringTypeExW(
        Locale: u32,  // DWORD
        dwInfoType: u32,  // DWORD
        lpSrcStr: *const u16,  // LPCWSTR
        cchSrc: i32,  // INT
        lpCharType: *mut u16  // WORD* out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("KERNEL32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
public static extern bool GetStringTypeExW(uint Locale, uint dwInfoType, [MarshalAs(UnmanagedType.LPWStr)] string lpSrcStr, int cchSrc, out ushort lpCharType);
"@
$api = Add-Type -MemberDefinition $sig -Name 'KERNEL32_GetStringTypeExW' -Namespace Win32 -PassThru
# $api::GetStringTypeExW(Locale, dwInfoType, lpSrcStr, cchSrc, lpCharType)

#uselib "KERNEL32.dll"
#func global GetStringTypeExW "GetStringTypeExW" wptr, wptr, wptr, wptr, wptr
; GetStringTypeExW Locale, dwInfoType, lpSrcStr, cchSrc, varptr(lpCharType)   ; 戻り値は stat
; Locale : DWORD -> "wptr"
; dwInfoType : DWORD -> "wptr"
; lpSrcStr : LPCWSTR -> "wptr"
; cchSrc : INT -> "wptr"
; lpCharType : WORD* out -> "wptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "KERNEL32.dll"
#cfunc global GetStringTypeExW "GetStringTypeExW" int, int, wstr, int, var
; res = GetStringTypeExW(Locale, dwInfoType, lpSrcStr, cchSrc, lpCharType)
; Locale : DWORD -> "int"
; dwInfoType : DWORD -> "int"
; lpSrcStr : LPCWSTR -> "wstr"
; cchSrc : INT -> "int"
; lpCharType : WORD* out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "KERNEL32.dll"
#cfunc global GetStringTypeExW "GetStringTypeExW" int, int, wstr, int, sptr
; res = GetStringTypeExW(Locale, dwInfoType, lpSrcStr, cchSrc, varptr(lpCharType))
; Locale : DWORD -> "int"
; dwInfoType : DWORD -> "int"
; lpSrcStr : LPCWSTR -> "wstr"
; cchSrc : INT -> "int"
; lpCharType : WORD* out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。