HSTRING

Windows ランタイム文字列へのハンドル。

typedef HSTRING__* HSTRING;

解説

HSTRING を使用して、Windows ランタイム内の変更できない文字列を表します。

JavaScript やその他の言語 (C#、Microsoft Visual Basic など) では、 HSTRING を使用して表される文字列を使用できます。 次の表は、 HSTRING が他の言語でどのように表されるかを示しています。

HSTRING ハンドルは標準ハンドル型です。 意味的には、値 NULL を含む HSTRING は、0 個のコンテンツ文字と終端の NULL 文字で構成される空の文字列を表します。 0 文字の WindowsCreateString を使用して文字列を作成すると、ハンドル値 NULL が生成されます。 値 NULL を指定して WindowsGetStringRawBuffer を呼び出すと、空の文字列へのポインターの後に続く NUL 終端文字のみが返されます。 初期化されていない HSTRING を表す個別の値は存在しません。

WindowsCreateString 関数を呼び出して新しい HSTRING を作成し、WindowsDeleteString 関数を呼び出してバッキング文字列メモリへの参照を解放します。 WindowsCreateStringReference 関数を呼び出して、高速パス文字列とも呼ばれる文字列参照を作成します。

WindowsDuplicateString 関数を呼び出して HSTRING をコピーします。

WindowsConcatString 関数を呼び出して、2 つの文字列を連結します。

WindowsGetStringRawBuffer 関数を呼び出して、バッキング文字列メモリにアクセスします。

HSTRING では、埋め込み NUL 文字を格納して使用できます。 予期しない結果が発生する可能性のある関数を使用する前に、WindowsStringHasEmbeddedNull 関数を使用して、埋め込まれた NUL 文字をチェックします。 たとえば、ほとんどの Windows 関数は入力パラメーターとして LPCWSTR を使用し、最初の NUL が検出されるまで文字列の長さを計算します。

バッキング文字列は不変であり、null で終わる必要があります。 コードを呼び出すと、 WindowsCreateStringReference 関数を使用して文字列参照が作成されます。バッキング文字列表現を含むメモリは呼び出し元によって所有されます。 Windows ランタイムは、元の文字列の内容に依存して変更されません。 文字列参照をWindows ランタイムに渡す場合、呼び出しの間、文字列の内容が変更されず、NUL が終了することを確認するのは呼び出し元の責任です。 Windows ランタイムは、呼び出しが返されたときに文字列参照へのすべての参照を解放します。

出力パラメーターとして HSTRING を受け取る場合は、処理が完了したときにハンドルを NULL に設定することをお勧めします。

変更できない HSTRING を作成するために使用できる変更可能な文字列バッファーを割り当てるには、WindowsPreallocateStringBuffer 関数を呼び出します。 バッファーの設定が完了したら、 WindowsPromoteStringBuffer 関数を呼び出して HSTRING を作成します。 この 2 フェーズ構築パターンにより、"文字列ビルダー" に似た機能が可能になります。

要件

関連項目

WindowsCreateString

WindowsDeleteString

WindowsDuplicateString

WindowsPreallocateStringBuffer