WindowsPreallocateStringBuffer 関数 (winstring.h)

[アーティクル]
03/13/2024

HSTRING の作成時に使用する変更可能な文字バッファーを割り当てます。

構文

HRESULT WindowsPreallocateStringBuffer(
  UINT32         length,
  WCHAR          **charBuffer,
  HSTRING_BUFFER *bufferHandle
);

パラメーター

length

型: [in] UINT32

割り当てるバッファーのサイズ。値 0 は空の文字列に対応します。

charBuffer

種類: [out] WCHAR**

文字を保持する変更可能なバッファー。バッファーには、終端の NULL 文字が既に含まれていることに注意してください。

bufferHandle

種類: [out] HSTRING_BUFFER*

事前に割り当てられた文字列バッファー。length が 0 の場合は NULL。

戻り値

型: HRESULT

この関数は、これらの値のいずれかを返すことができます。

リターンコード	説明
S_OK	HSTRING が正常に作成されました。
E_POINTER	mutableBuffer または bufferHandle が NULL です。
MEM_E_INVALID_SIZE	要求された HSTRING 割り当てサイズが大きすぎます。
E_OUTOFMEMORY	HSTRING を割り当てませんでした。

注釈

変更できない HSTRING にコミットする前に操作できる変更可能な文字バッファーを作成するには、WindowsPreallocateStringBuffer 関数を使用します。 mutableBuffer に文字列を設定したら、bufferHandle パラメーターを使用して WindowsPromoteStringBuffer 関数を呼び出して HSTRING を作成します。バッファーに正確に 長さの 文字を書き込む必要があります。 Windows 10 バージョン 1803、Windows Server バージョン 1803 以降: 長さ文字の後に null 終端記号を記述できます。

昇格する前に変更可能なバッファーを破棄するには、 WindowsDeleteStringBuffer 関数を呼び出します。バッファーが WindowsPromoteStringBuffer の呼び出しによって既に昇格されている場合は、WindowsDeleteString 関数を呼び出して文字列を破棄します。 WindowsPromoteStringBuffer 呼び出しが失敗した場合は、WindowsDeleteStringBuffer 関数を呼び出して、変更可能なバッファーを破棄できます。

例

次のコード例では、 WindowsPreallocateStringBuffer 関数の使用方法を示します。

#include <winstring.h>

int main()
{
    HSTRING hString = NULL;
    HSTRING_BUFFER hStringBuffer = NULL;
    PWSTR strBuffer = NULL;

    HRESULT hr = WindowsPreallocateStringBuffer(10, &strBuffer, &hStringBuffer);

    if (SUCCEEDED(hr))
    {
        CopyMemory(strBuffer, L"1234567890", 10 * sizeof(wchar_t));
        hr = WindowsPromoteStringBuffer(hStringBuffer, &hString);
    }

    WindowsDeleteString(hString);  
}

要件

要件	値
サポートされている最小のクライアント	Windows 8 [デスクトップアプリ \|UWP アプリ]
サポートされている最小のサーバー	Windows Server 2012 [デスクトップアプリ \|UWP アプリ]
対象プラットフォーム	Windows
ヘッダー	winstring.h
Library	RuntimeObject.lib
[DLL]	ComBase.dll