IsTextUnicode

関数

バッファ内容がUnicodeテキストか判定する。

DLLADVAPI32.dll呼出規約winapi対応OSWindows 2000 以降

シグネチャ

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

BOOL IsTextUnicode(
    const void* lpv,
    INT iSize,
    IS_TEXT_UNICODE_RESULT* lpiResult   // optional
);

パラメーター

名前

型

方向

説明

lpv

void*

検査対象の入力バッファへのポインター。

iSize

INT

lpv が示す入力バッファのサイズ(バイト単位)。

lpiResult

IS_TEXT_UNICODE_RESULT*

inoutoptional

入力時には、入力バッファのテキストに適用するテストを指すポインター。出力時には、このパラメーターに指定したテストの結果が格納されます。バッファの内容がテストに合格した場合は 1、不合格の場合は 0 です。出力時に意味を持つのは、関数への入力時に設定されていたフラグのみです。

lpiResult が NULL の場合、関数は利用可能なすべてのテストを使用して、バッファ内のデータが Unicode テキストである可能性が高いかどうかを判定します。

このパラメーターには、次の値の 1 つ以上を指定できます。値は二項 "OR" で組み合わせることができます。

値	意味
IS_TEXT_UNICODE_ASCII16	テキストは Unicode であり、ゼロ拡張された ASCII の値/文字のみを含みます。
IS_TEXT_UNICODE_REVERSE_ASCII16	上記と同じですが、Unicode テキストのバイト順が反転している点が異なります。
IS_TEXT_UNICODE_STATISTICS	テキストはおそらく Unicode です。判定は統計的分析を適用して行われます。絶対的な確実性は保証されません。「解説」セクションを参照してください。
IS_TEXT_UNICODE_REVERSE_STATISTICS	上記と同じですが、おそらく Unicode であるテキストのバイト順が反転している点が異なります。
IS_TEXT_UNICODE_CONTROLS	テキストには、次の非表示文字のうち 1 つ以上の Unicode 表現が含まれます: RETURN、LINEFEED、SPACE、CJK_SPACE、TAB。
IS_TEXT_UNICODE_REVERSE_CONTROLS	上記と同じですが、Unicode 文字のバイト順が反転している点が異なります。
IS_TEXT_UNICODE_BUFFER_TOO_SMALL	意味のある分析を行うには、バッファ内の文字数が少なすぎます(2 バイト未満)。
IS_TEXT_UNICODE_SIGNATURE	テキストの先頭文字として、Unicode バイト順マーク (BOM) 0xFEFF が含まれます。
IS_TEXT_UNICODE_REVERSE_SIGNATURE	テキストの先頭文字として、バイト順が反転した Unicode バイト順マーク (Reverse BOM) 0xFFFE が含まれます。
IS_TEXT_UNICODE_ILLEGAL_CHARS	テキストには、次の Unicode で不正な文字のいずれかが含まれます: 埋め込まれた Reverse BOM、UNICODE_NUL、CRLF(1 ワードにまとめられたもの)、または 0xFFFF。
IS_TEXT_UNICODE_ODD_LENGTH	文字列の文字数が奇数です。奇数長の文字列は(定義上)Unicode テキストにはなり得ません。
IS_TEXT_UNICODE_NULL_BYTES	テキストには null バイトが含まれており、これは非 ASCII テキストであることを示します。
IS_TEXT_UNICODE_UNICODE_MASK	値は IS_TEXT_UNICODE_ASCII16、IS_TEXT_UNICODE_STATISTICS、IS_TEXT_UNICODE_CONTROLS、IS_TEXT_UNICODE_SIGNATURE の組み合わせです。
IS_TEXT_UNICODE_REVERSE_MASK	値は IS_TEXT_UNICODE_REVERSE_ASCII16、IS_TEXT_UNICODE_REVERSE_STATISTICS、IS_TEXT_UNICODE_REVERSE_CONTROLS、IS_TEXT_UNICODE_REVERSE_SIGNATURE の組み合わせです。
IS_TEXT_UNICODE_NOT_UNICODE_MASK	値は IS_TEXT_UNICODE_ILLEGAL_CHARS、IS_TEXT_UNICODE_ODD_LENGTH、および現在未使用の 2 つのビットフラグの組み合わせです。
IS_TEXT_UNICODE_NOT_ASCII_MASK	値は IS_TEXT_UNICODE_NULL_BYTES および現在未使用の 3 つのビットフラグの組み合わせです。

戻り値の型: BOOL

公式ドキュメント

バッファが何らかの形式の Unicode テキストを含んでいる可能性が高いかどうかを判定します。

戻り値

バッファ内のデータが指定したテストに合格した場合は 0 以外の値を返します。バッファ内のデータが指定したテストに合格しなかった場合、関数は 0 を返します。

解説(Remarks)

この関数は、lpiResult パラメーターで渡されるフラグの制御のもと、さまざまな統計的手法および決定論的手法を使用して判定を行います。関数が制御を返すと、それらのテストの結果が同じパラメーターを使用して報告されます。

IS_TEXT_UNICODE_STATISTICS および IS_TEXT_UNICODE_REVERSE_STATISTICS のテストは統計的分析を使用します。これらのテストは確実ではありません。統計的テストは、文字列内の下位バイトと上位バイトの間に一定量のばらつきがあることを前提としているため、一部の ASCII 文字列はすり抜けることがあります。たとえば、lpv が ASCII 文字列 0x41、0x0A、0x0D、0x1D (A\n\r^Z) を示している場合、本来は不合格となるほうが望ましいにもかかわらず、この文字列は IS_TEXT_UNICODE_STATISTICS テストに合格します。

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

各言語での呼び出し定義

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

BOOL IsTextUnicode(
    const void* lpv,
    INT iSize,
    IS_TEXT_UNICODE_RESULT* lpiResult   // optional
);

[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("ADVAPI32.dll", ExactSpelling = true)]
static extern bool IsTextUnicode(
    IntPtr lpv,   // void*
    int iSize,   // INT
    IntPtr lpiResult   // IS_TEXT_UNICODE_RESULT* optional, in/out
);

<DllImport("ADVAPI32.dll", ExactSpelling:=True)>
Public Shared Function IsTextUnicode(
    lpv As IntPtr,   ' void*
    iSize As Integer,   ' INT
    lpiResult As IntPtr   ' IS_TEXT_UNICODE_RESULT* optional, in/out
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function

' lpv : void*
' iSize : INT
' lpiResult : IS_TEXT_UNICODE_RESULT* optional, in/out
Declare PtrSafe Function IsTextUnicode Lib "advapi32" ( _
    ByVal lpv As LongPtr, _
    ByVal iSize As Long, _
    ByVal lpiResult As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

IsTextUnicode = ctypes.windll.advapi32.IsTextUnicode
IsTextUnicode.restype = wintypes.BOOL
IsTextUnicode.argtypes = [
    ctypes.POINTER(None),  # lpv : void*
    ctypes.c_int,  # iSize : INT
    ctypes.c_void_p,  # lpiResult : IS_TEXT_UNICODE_RESULT* optional, in/out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ADVAPI32.dll')
IsTextUnicode = Fiddle::Function.new(
  lib['IsTextUnicode'],
  [
    Fiddle::TYPE_VOIDP,  # lpv : void*
    Fiddle::TYPE_INT,  # iSize : INT
    Fiddle::TYPE_VOIDP,  # lpiResult : IS_TEXT_UNICODE_RESULT* optional, in/out
  ],
  Fiddle::TYPE_INT)

#[link(name = "advapi32")]
extern "system" {
    fn IsTextUnicode(
        lpv: *const (),  // void*
        iSize: i32,  // INT
        lpiResult: *mut u32  // IS_TEXT_UNICODE_RESULT* optional, in/out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("ADVAPI32.dll")]
public static extern bool IsTextUnicode(IntPtr lpv, int iSize, IntPtr lpiResult);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ADVAPI32_IsTextUnicode' -Namespace Win32 -PassThru
# $api::IsTextUnicode(lpv, iSize, lpiResult)

#uselib "ADVAPI32.dll"
#func global IsTextUnicode "IsTextUnicode" sptr, sptr, sptr
; IsTextUnicode lpv, iSize, varptr(lpiResult)   ; 戻り値は stat
; lpv : void* -> "sptr"
; iSize : INT -> "sptr"
; lpiResult : IS_TEXT_UNICODE_RESULT* optional, in/out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "ADVAPI32.dll"
#cfunc global IsTextUnicode "IsTextUnicode" sptr, int, var
; res = IsTextUnicode(lpv, iSize, lpiResult)
; lpv : void* -> "sptr"
; iSize : INT -> "int"
; lpiResult : IS_TEXT_UNICODE_RESULT* optional, in/out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "ADVAPI32.dll"
#cfunc global IsTextUnicode "IsTextUnicode" sptr, int, sptr
; res = IsTextUnicode(lpv, iSize, varptr(lpiResult))
; lpv : void* -> "sptr"
; iSize : INT -> "int"
; lpiResult : IS_TEXT_UNICODE_RESULT* optional, in/out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。