ホーム › Storage.Imapi › IWriteEngine2

IWriteEngine2

COMIDispatch (デュアル)

📘 Microsoft Learn (日本語) · English

✅ IDispatch を実装(デュアルインターフェース)。HSP では comobj 経由でメソッド名による遅延バインド呼び出しができます(vtableインデックス不要)。

IID27354135-7f64-5b0f-8f00-5d77afbe261e継承元IDispatch呼び出し名前(IDispatch) または vtbl自前メソッド開始 vtbl7

公式ドキュメント

デバイスにデータストリームを書き込むには、このインターフェイスを使用します。

解説(Remarks)

スクリプトで MsftWriteEngine2 オブジェクトを作成するには、CreateObject を呼び出す際にプログラム識別子として IMAPI2.MsftWriteEngine2 を使用します。

書き込み操作の実行中に電源状態の遷移 (ユーザーのログオフやシステムのサスペンドなど) が発生することがあり、その場合は書き込み処理が中断されてデータが失われるおそれがあります。プログラミング上の考慮事項については、書き込み中のログオフまたはサスペンドの防止を参照してください。

メソッド 13

vtbl = vtable インデックス(0始まり)。IDispatch 実装のため HSP ではメソッド名でも呼べます(上記)。低レベルの index 呼び出し用に vtbl も掲載。0〜2 は IUnknown。

vtbl 7 HRESULT WriteSection(IStream* data, INT startingBlockAddress, INT numberOfBlocks)

現在のレコーダーにデータストリームを書き込みます。

data	IStream*	in	レコーダーに書き込むデータストリームの IStream インターフェイスです。
startingBlockAddress	INT	in	書き込み操作の開始論理ブロックアドレス (LBA) です。負の値もサポートされます。
numberOfBlocks	INT	in	データストリームから書き込むブロック数です。

戻り値

成功した場合は S_OK が返されますが、実装によってはその他の成功コードが返されることもあります。操作が失敗した場合は一般に次のエラーコードが返されますが、返される可能性のあるエラー値はこれらに限りません。

戻り値	説明
E_POINTER	ポインターが無効です。値: 0x80004003
E_OUTOFMEMORY	必要なメモリの割り当てに失敗しました。値: 0x8007000E
E_INVALIDARG	1 つ以上の引数が無効です。値: 0x80070057
E_IMAPI_REQUEST_CANCELLED	要求が取り消されました。値: 0xC0AA0002

解説(Remarks)

このメソッドを呼び出す前に、記録デバイスを指定するために IWriteEngine2::put_Recorder メソッドを、書き込み時に各セクターで使用するバイト数を指定するために IWriteEngine2::put_BytesPerSector メソッドを呼び出す必要があります。

また、既定値がアプリケーションに適さない場合は、次のメソッドの呼び出しも検討してください。

このメソッドは同期的に動作します。書き込み操作の進行状況を把握するには、DWriteEngine2Events インターフェイスを実装する必要があります。スクリプトでイベントハンドラーを実装する方法を示す例については、イベントによる進行状況の監視を参照してください。

vtbl 8 HRESULT CancelWrite()

進行中の書き込み操作を取り消します。

戻り値

成功した場合は次の値が返されますが、実装によってはその他の成功コードが返されることもあります。操作が失敗した場合は一般に次のエラーコードが返されますが、返される可能性のあるエラー値はこれらに限りません。

戻り値	説明
S_OK	メソッドは成功しました。
S_IMAPI_WRITE_NOT_IN_PROGRESS	直前の IWriteEngine2::WriteSection の呼び出しで開始された書き込み操作がまだ始まっておらず、取り消すことができません。別の成功コードが返されるまで IWriteEngine2::CancelWrite を呼び出し続けることをお勧めします。値: 0x00AA0302L

操作が失敗した場合は一般に次のエラーコードが返されますが、返される可能性のあるエラー値はこれらに限りません。

戻り値	説明
E_FAIL	原因不明のエラーです。値: 0x80004005

解説(Remarks)

書き込み操作を取り消すには、実装した DWriteEngine2Events::Update イベントハンドラーからこのメソッドを呼び出す必要があります。

vtbl 9 HRESULT put_Recorder(IDiscRecorder2Ex* value)

書き込み操作に使用する記録デバイスを設定します。

value

IDiscRecorder2Ex*

書き込み操作で使用する記録デバイスを識別する IDiscRecorder2Ex インターフェイスです。

戻り値

戻り値	説明
E_POINTER	ポインターが無効です。値: 0x80004003
E_FAIL	原因不明のエラーです。値: 0x80004005
E_OUTOFMEMORY	必要なメモリの割り当てに失敗しました。値: 0x8007000E
E_INVALIDARG	1 つ以上の引数が無効です。値: 0x80070057
E_IMAPI_RECORDER_COMMAND_TIMEOUT	デバイスがタイムアウト期間内にコマンドを受け付けませんでした。デバイスが不整合な状態になっているか、コマンドのタイムアウト値を長くする必要がある可能性があります。値: 0xC0AA020D
E_IMAPI_RECORDER_INVALID_RESPONSE_FROM_DEVICE	デバイスがコマンドに対して予期しないデータまたは無効なデータを報告しました。値: 0xC0AA02FF
E_IMAPI_RECORDER_MEDIA_UPSIDE_DOWN	メディアが裏返しに挿入されています。値: 0xC0AA0204
E_IMAPI_RECORDER_MEDIA_BECOMING_READY	ドライブは準備中であると報告しました。しばらくしてから要求をやり直してください。値: 0xC0AA0205
E_IMAPI_RECORDER_MEDIA_NO_MEDIA	デバイスにメディアがありません。値: 0xC0AA0202
E_IMAPI_RECORDER_MEDIA_FORMAT_IN_PROGRESS	メディアは現在フォーマット中です。メディアを使用する前に、フォーマットが完了するまでお待ちください。値: 0xC0AA0206
E_IMAPI_RECORDER_MEDIA_BUSY	ドライブは、書き込みの終了処理などの長時間実行される操作を実行中であると報告しました。ドライブは長時間にわたって使用できない可能性があります。値: 0xC0AA0207
E_IMAPI_LOSS_OF_STREAMING	ドライブが書き込みを継続できるだけの速さでデータを受け取れなかったため、書き込みに失敗しました。ソースデータをローカルコンピューターに移動する、書き込み速度を下げる、または「バッファーアンダーラン防止」設定を有効にすることで、この問題が解決する場合があります。値: 0xC0AA0300
E_IMAPI_RECORDER_MEDIA_INCOMPATIBLE	メディアに互換性がないか、物理フォーマットが不明です。値: 0xC0AA0203
E_IMAPI_RECORDER_DVD_STRUCTURE_NOT_PRESENT	DVD 構造が存在しません。互換性のないドライブまたはメディアを使用していることが原因である可能性があります。値: 0xC0AA020E
E_IMAPI_RECORDER_NO_SUCH_MODE_PAGE	デバイスは、要求されたモードページ (およびその種類) が存在しないと報告しました。値: 0xC0AA0201
E_IMAPI_RECORDER_INVALID_MODE_PARAMETERS	ドライブは、MODE SELECT コマンドのモードページで指定されたパラメーターの組み合わせがサポートされていないと報告しました。値: 0xC0AA0208
E_IMAPI_RECORDER_MEDIA_WRITE_PROTECTED	ドライブは、メディアが書き込み禁止であると報告しました。値: 0xC0AA0209
E_IMAPI_RECORDER_MEDIA_SPEED_MISMATCH	メディアの速度がデバイスと互換性がありません。デバイスがサポートする速度範囲より高速または低速のメディアを使用していることが原因である可能性があります。値: 0xC0AA020F
HRESULT_FROM_WIN32(ERROR_INVALID_HANDLE)	指定されたハンドルが無効です。値: 6
HRESULT_FROM_WIN32(ERROR_DEV_NOT_EXIST)	指定されたネットワークリソースまたはデバイスは、使用できなくなりました。値: 55
E_IMAPI_RECORDER_LOCKED	直前の操作でこのレコーダーに関連付けられたデバイスが排他的にロックされているため、この操作は失敗しました。値: 0xC0AA0210

vtbl 10 HRESULT get_Recorder(IDiscRecorder2Ex** value)

書き込み操作に使用する記録デバイスを取得します。

value

IDiscRecorder2Ex**

out

書き込み操作で使用する記録デバイスを識別する IDiscRecorder2Ex インターフェイスです。

戻り値

戻り値	説明
E_POINTER	ポインターが無効です。値: 0x80004003

vtbl 11 HRESULT put_UseStreamingWrite12(VARIANT_BOOL value)

書き込み操作で WRITE12 コマンドと WRITE10 コマンドのどちらを使用するかを示す値を設定します。

value

VARIANT_BOOL

ディスクへの書き込み時に、ストリーミングビットを 1 に設定した WRITE12 コマンドを使用する場合は VARIANT_TRUE を設定します。WRITE10 コマンドを使用する場合は VARIANT_FALSE を設定します。既定値は VARIANT_FALSE です。

戻り値

戻り値	説明
E_NOTIMPL	このプロパティを VARIANT_TRUE に設定することは、現在サポートされていません。値: 0x80004001
E_FAIL	原因不明のエラーです。値: 0x80004005

vtbl 12 HRESULT get_UseStreamingWrite12(VARIANT_BOOL* value)

書き込み操作で WRITE12 コマンドと WRITE10 コマンドのどちらを使用するかを示す値を取得します。

value

VARIANT_BOOL*

out

VARIANT_TRUE の場合、書き込み操作はストリーミングビットを 1 に設定した WRITE12 コマンドを使用します。VARIANT_FALSE の場合、書き込み操作は WRITE10 コマンドを使用します。

戻り値

戻り値	説明
E_POINTER	ポインターが無効です。値: 0x80004003

vtbl 13 HRESULT put_StartingSectorsPerSecond(INT value)

書き込み処理の開始時に記録デバイスがメディアへ書き込める 1 秒あたりのセクター数の推定値を設定します。

value

INT

書き込み処理の開始時に記録デバイスがメディアへ書き込める 1 秒あたりのおおよそのセクター数です。既定値は -1 で、最大速度を意味します。

戻り値

戻り値	説明
E_FAIL	原因不明のエラーです。値: 0x80004005
E_INVALIDARG	1 つ以上の引数が無効です。値: 0x80070057

解説(Remarks)

これは、書き込みエンジンにおけるスリープ時間の最適化に使用されます。

vtbl 14 HRESULT get_StartingSectorsPerSecond(INT* value)

書き込み処理の開始時に記録デバイスがメディアへ書き込める 1 秒あたりのセクター数の推定値を取得します。

value

INT*

out

書き込み処理の開始時に記録デバイスがメディアへ書き込める 1 秒あたりのおおよそのセクター数です。

値が -1 の場合は最大速度を示します。

戻り値

戻り値	説明
E_POINTER	ポインターが無効です。値: 0x80004003

vtbl 15 HRESULT put_EndingSectorsPerSecond(INT value)

書き込み処理の終了時に記録デバイスがメディアへ書き込める 1 秒あたりのセクター数の推定値を設定します。

value

INT

書き込み処理の終了時に記録デバイスがメディアへ書き込める 1 秒あたりのおおよそのセクター数です。既定値は -1 で、最大速度を意味します。

戻り値

戻り値	説明
E_FAIL	原因不明のエラーです。値: 0x80004005
E_INVALIDARG	1 つ以上の引数が無効です。値: 0x80070057

解説(Remarks)

これは、書き込みエンジンにおけるスリープ時間の最適化に使用されます。

vtbl 16 HRESULT get_EndingSectorsPerSecond(INT* value)

書き込み処理の終了時に記録デバイスがメディアへ書き込める 1 秒あたりのセクター数の推定値を取得します。

value

INT*

out

書き込み処理の終了時に記録デバイスがメディアへ書き込める 1 秒あたりのおおよそのセクター数です。

値が -1 の場合は最大速度を示します。

戻り値

戻り値	説明
E_POINTER	ポインターが無効です。値: 0x80004003

vtbl 17 HRESULT put_BytesPerSector(INT value)

書き込み時に各セクターで使用するバイト数を設定します。

value

INT

書き込み時に各セクターで使用するバイト数です。最小サイズは 1 バイト、最大サイズは MAXLONG バイトです。通常、CD メディアではこの値は 2,048 バイトですが、任意のサイズ (2352 や 2448 など) もサポートされます。この値は IDiscRecorder2Ex::GetMaximumPageAlignedTransferSize によって制限され、その値は通常 65,536 (64K) バイトです。

戻り値

戻り値	説明
E_FAIL	原因不明のエラーです。値: 0x80004005
E_INVALIDARG	1 つ以上の引数が無効です。値: 0x80070057

解説(Remarks)

論理ブロックサイズを指定する必要があります。

vtbl 18 HRESULT get_BytesPerSector(INT* value)

書き込み時に各セクターで使用するバイト数を取得します。返される値は、以前に IWriteEngine2::put_BytesPerSector で設定された値を示すものであり、メディアの現在の 1 セクターあたりのバイト数を返すものではありません。

value

INT*

out

書き込み時に各セクターで使用するバイト数です。

メモ IWriteEngine2::put_BytesPerSector が呼び出されていない場合、このパラメーターは '-1' という値を示します。

戻り値

戻り値	説明
E_POINTER	ポインターが無効です。値: 0x80004003

vtbl 19 HRESULT get_WriteInProgress(VARIANT_BOOL* value)

レコーダーが現在ディスクにデータを書き込んでいるかどうかを示す値を取得します。

value

VARIANT_BOOL*

out

VARIANT_TRUE の場合、レコーダーは現在ディスクにデータを書き込んでいます。VARIANT_FALSE の場合、レコーダーは現在ディスクに書き込んでいません。

戻り値

戻り値	説明
E_POINTER	ポインターが無効です。値: 0x80004003

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

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数:

#define global IID_IWriteEngine2 "{27354135-7F64-5B0F-8F00-5D77AFBE261E}"
#usecom global IWriteEngine2 IID_IWriteEngine2 "{}"
#comfunc global IWriteEngine2_WriteSection                  7 sptr,int,int
#comfunc global IWriteEngine2_CancelWrite                   8
#comfunc global IWriteEngine2_put_Recorder                  9 sptr
#comfunc global IWriteEngine2_get_Recorder                  10 sptr
#comfunc global IWriteEngine2_put_UseStreamingWrite12       11 int
#comfunc global IWriteEngine2_get_UseStreamingWrite12       12 var
#comfunc global IWriteEngine2_put_StartingSectorsPerSecond  13 int
#comfunc global IWriteEngine2_get_StartingSectorsPerSecond  14 var
#comfunc global IWriteEngine2_put_EndingSectorsPerSecond    15 int
#comfunc global IWriteEngine2_get_EndingSectorsPerSecond    16 var
#comfunc global IWriteEngine2_put_BytesPerSector            17 int
#comfunc global IWriteEngine2_get_BytesPerSector            18 var
#comfunc global IWriteEngine2_get_WriteInProgress           19 var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。
; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。#define global IID_IWriteEngine2 "{27354135-7F64-5B0F-8F00-5D77AFBE261E}"
#usecom global IWriteEngine2 IID_IWriteEngine2 "{}"
#comfunc global IWriteEngine2_WriteSection                  7 sptr,int,int
#comfunc global IWriteEngine2_CancelWrite                   8
#comfunc global IWriteEngine2_put_Recorder                  9 sptr
#comfunc global IWriteEngine2_get_Recorder                  10 sptr
#comfunc global IWriteEngine2_put_UseStreamingWrite12       11 int
#comfunc global IWriteEngine2_get_UseStreamingWrite12       12 sptr
#comfunc global IWriteEngine2_put_StartingSectorsPerSecond  13 int
#comfunc global IWriteEngine2_get_StartingSectorsPerSecond  14 sptr
#comfunc global IWriteEngine2_put_EndingSectorsPerSecond    15 int
#comfunc global IWriteEngine2_get_EndingSectorsPerSecond    16 sptr
#comfunc global IWriteEngine2_put_BytesPerSector            17 int
#comfunc global IWriteEngine2_get_BytesPerSector            18 sptr
#comfunc global IWriteEngine2_get_WriteInProgress           19 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。
; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。