IDiscRecorder

COM

IID85ac9776-ca88-4cf2-894e-09598c078a41継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

IDiscRecorder インターフェースは、アクティブなディスクレコーダーと呼ばれる単一のディスクレコーダーデバイスへのアクセスを可能にします。MSDiscMasterObj などの IMAPI オブジェクトが、アクティブなディスクレコーダーを保持します。

解説(Remarks)

すべての IDiscRecorder のメソッドは、対象のディスクレコーダーがアクティブなディスクレコーダーでない場合でも、 IDiscRecorder オブジェクトに対して使用できます。IMAPI クライアントは、事前に IDiscMaster::SetActiveDiscRecorder を呼び出す必要はありません。

メソッド 15

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT Init(BYTE* pbyUniqueID, DWORD nulIDSize, DWORD nulDriveNumber)

pbyUniqueID	BYTE*	in	レコーダーを一意に識別する ID を格納したバイトバッファへのポインタである。
nulIDSize	DWORD	in	ID バッファのサイズをバイト単位で指定する。
nulDriveNumber	DWORD	in	レコーダーに対応するドライブ番号を指定する。

vtbl 4 HRESULT GetRecorderGUID(BYTE* pbyUniqueID, DWORD ulBufferSize, DWORD* pulReturnSizeRequired)

レコーダーオブジェクトに現在関連付けられている物理ディスクレコーダーの GUID を取得します。

pbyUniqueID	BYTE*	inoutoptional	このレコーダーの現在の GUID 情報が格納される GUID バッファーへのポインター。必要なバッファーサイズを問い合わせるには NULL を指定します。
ulBufferSize	DWORD	in	GUID バッファーのサイズ。pbyUniqueID が NULL の場合、このパラメーターはゼロでなければなりません。
pulReturnSizeRequired	DWORD*	out	GUID 情報のサイズ。

戻り値

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

vtbl 5 HRESULT GetRecorderType(RECORDER_TYPES* fTypeCode)

ディスクレコーダーが CD-R デバイスか CD-RW デバイスかを判別します。これは、デバイスに現在挿入されているメディアの種類を示すものではありません。

fTypeCode

RECORDER_TYPES*

out

次のいずれかの値。

値	意味
RECORDER_CDR	0x1
RECORDER_CDRW	0x2

戻り値

vtbl 6 HRESULT GetDisplayNames(LPWSTR* pbstrVendorID, LPWSTR* pbstrProductID, LPWSTR* pbstrRevision)

表示に使用できる、整形されたレコーダー名を取得します。この名前はデバイスの製造元と製品識別子で構成されます。

pbstrVendorID	LPWSTR*	inoutoptional	ディスクレコーダーのベンダー。このパラメーターには NULL を指定できます。
pbstrProductID	LPWSTR*	inoutoptional	ディスクレコーダーの製品名。このパラメーターには NULL を指定できます。
pbstrRevision	LPWSTR*	inoutoptional	ディスクレコーダーのリビジョン。通常はレコーダーのファームウェアのリビジョンですが、デバイス全体のリビジョンである場合もあります。このパラメーターには NULL を指定できます。

戻り値

解説(Remarks)

これらの表示名は通常、レコーダー選択用のリストボックスやその他の GUI コンポーネントに表示する 1 つの文字列に結合して使用されます。

これら 3 つの文字列を組み合わせても、その特定のレコーダーを一意に識別する識別子にはなりません。一意の値を作成するには、これらの文字列と GetPath が返す文字列を組み合わせてください。

vtbl 7 HRESULT GetBasePnPID(LPWSTR* pbstrBasePnPID)

特定のクラスのデバイスをメーカーとモデルによって一貫して識別するために使用できる、基本 PnP 文字列を取得します。アプリケーションはこの文字列を使用して、レコーダーの種類に応じた動作のカスタマイズを行えます。

pbstrBasePnPID

LPWSTR*

out

基本 PnP ID 文字列。この文字列は、レコーダーの製造元、製品 ID、および (利用可能な場合は) リビジョン情報を連結したものです。

戻り値

vtbl 8 HRESULT GetPath(LPWSTR* pbstrPath)

オペレーティングシステム内でのデバイスへのパスを取得します。このパスは、利用可能なディスクレコーダーを完全に識別するために、表示名と組み合わせて使用してください。

pbstrPath

LPWSTR*

out

ディスクレコーダーへのパス。このパスは \Device\CdRomX の形式になる場合がありますが、この規則に従うことを前提にしないでください。

戻り値

vtbl 9 HRESULT GetRecorderProperties(IPropertyStorage** ppPropStg)

IPropertyStorage インターフェースへのポインターを取得します。

ppPropStg

IPropertyStorage**

out

現在のプロパティがすべて定義されたプロパティセットの IPropertyStorage インターフェースへのポインター。

戻り値

解説(Remarks)

プロパティは IMAPI を閉じた後は保持されません。プロパティセット形式は、ID/TYPE/VALUE の組み合わせと ID/NAME の関連付けを格納できるため、IMAPI にとって扱いやすい形式です。各組み合わせが 1 つのプロパティであり、IMAPI は特定のレコーダーに固有のさまざまな値にこれらのプロパティを使用します。たとえば、ほとんどのレコーダーは WriteSpeed プロパティをサポートします。

呼び出し元は、 SetRecorderProperties を呼び出すことでプロパティを変更できます。現在のプロパティには次のものがあります。

vtbl 10 HRESULT SetRecorderProperties(IPropertyStorage* pPropStg)

アプリケーションが変更したいプロパティをすべて保持するオブジェクトの IPropertyStorage ポインターを受け取ります。一部のプロパティのみを指定する設定もサポートされます。

pPropStg

IPropertyStorage*

inoptional

ディスクレコーダーがさまざまなプロパティの新しい設定を取得するために使用できる IPropertyStorage インターフェースへのポインター。

戻り値

解説(Remarks)

MaxWriteSpeed など、一部のプロパティは読み取り専用です。読み取り専用のプロパティとサポートされていないプロパティは、いずれもエラーを発生させることなく無視されます (IMAPI_S_PROPERTIESIGNORED を参照してください)。たとえば、このインターフェースにプロパティセットを渡して MaxWriteSpeed プロパティと ClearlyNeverHeardOfBefore プロパティを変更しようとした場合、MaxWriteSpeed は読み取り専用であり、ClearlyNeverHeardOfBefore は不明な値であるため、どちらのプロパティも無視され、メソッドは成功します。

SetRecorderProperties を呼び出した後、アプリケーションは GetRecorderProperties を呼び出してプロパティの設定内容を確認してください。

vtbl 11 HRESULT GetRecorderState(DISC_RECORDER_STATE_FLAGS* pulDevStateFlags)

ディスクレコーダーの状態を取得します。

pulDevStateFlags

DISC_RECORDER_STATE_FLAGS*

out

次のいずれかの値。

値	意味
RECORDER_BURNING	0x2
RECORDER_DOING_NOTHING	0x0
RECORDER_OPENED	0x1

戻り値

vtbl 12 HRESULT OpenExclusive()

ディスクレコーダーを排他アクセス用に開きます。

戻り値

解説(Remarks)

このメソッドは、エクスプローラーなどのアプリケーションからレコーダーへのファイルシステムアクセスをブロックします。次のメソッドを使用するには、事前にこのメソッドでレコーダーを開いておく必要があります。 QueryMediaType、 Eject、 Erase、 Close。

IDiscMaster::RecordDisc を呼び出す前にレコーダーを閉じることが重要です。閉じていない場合、この呼び出しは IMAPI_E_DEVICE_NOTACCESSIBLE で失敗します。デバイスは IDiscRecorder または IDiscMaster のいずれか一方からのアクセスに排他的に割り当てられ、両方を同時に使用することはできません。これは、アプリケーションによる制御中や書き込み中に、許可される操作やレコーダーの所有権について混乱が生じないようにするためです。

排他ロックの保持時間はできる限り短くしてください。オペレーティングシステムの他のコンポーネントからの要求は、後で実行するためにキューに入れられることはなく、単に失敗します。これは、書き込みが進行中であることを認識していないユーザーに混乱を与える可能性があります。

OpenExclusive を呼び出すと、ファイルシステムからはディスクが取り出されたように見えます。対応する Close を呼び出すと、ファイルシステムからはメディアが再び現れたように見えます。これにより自動実行に関する問題が発生する場合があります。

vtbl 13 HRESULT QueryMediaType(MEDIA_TYPES* fMediaType, MEDIA_FLAGS* fMediaFlags)

レコーダーに現在挿入されているメディアの種類を検出します (メディアが存在する場合)。

fMediaType

MEDIA_TYPES*

out

メディアがない場合、fMediaType と fMediaFlags はどちらもゼロになります。メディアがある場合、fMediaType には次の値が 1 つ以上格納されます。

値	意味
MEDIA_CD_EXTRA	4
MEDIA_CD_I	3
MEDIA_CD_OTHER	5
MEDIA_CD_ROM_XA	2
MEDIA_CDDA_CDROM	1
MEDIA_SPECIAL	6

fMediaFlags

MEDIA_FLAGS*

out

メディアがある場合、このパラメーターには次の値が 1 つ以上格納されます。

値	意味
MEDIA_BLANK	0x1
MEDIA_RW	0x2
MEDIA_WRITABLE	0x4

戻り値

vtbl 14 HRESULT QueryMediaInfo(BYTE* pbSessions, BYTE* pbLastTrack, DWORD* ulStartAddress, DWORD* ulNextWritable, DWORD* ulFreeBlocks)

メディア上で使用されているブロックの総数など、現在マウントされているメディアに関する情報を取得します。

pbSessions	BYTE*	out	ディスク上のセッション数。
pbLastTrack	BYTE*	out	直前のセッションの最終トラックのトラック番号。
ulStartAddress	DWORD*	out	直前のセッションの最終トラックの開始アドレス。
ulNextWritable	DWORD*	out	書き込みを開始するアドレス。
ulFreeBlocks	DWORD*	out	書き込みに使用できるブロック数。

戻り値

解説(Remarks)

このメソッドを使用すると、排他的な開放を伴うアクティブなディスクレコーダーの設定を使わずに、ディスクの残り空き容量などのパラメーターを算出できます。ディスクの総容量は、次に書き込み可能なアドレスと空きブロック数を合計することで求められます。

vtbl 15 HRESULT Eject()

可能な場合、ディスクレコーダーのトレイのロックを解除して取り出します。

戻り値

解説(Remarks)

すべてのレコーダーがメディアを取り出す呼び出しをサポートしているわけではありません。ただし、このメソッドはメディアの取り出しを試みます。

vtbl 16 HRESULT Erase(BYTE bFullErase)

CD-RW ディスクレコーダーである場合に、CD-RW メディアの消去を試みます。フル消去とクイック消去の両方がサポートされます。

bFullErase

BYTE

消去の種類を指定します。このパラメーターが FALSE の場合はクイック消去が実行されます。TRUE の場合はフル消去が実行されます。

戻り値

解説(Remarks)

ディスクの消去は非常に時間のかかる操作になることがあります (1 時間を超える場合もあります)。消去完了の通知を受け取るには、IDiscMasterProgressEvents::NotifyEraseComplete を使用します。

クイック消去では、PMA、最初のセッションの TOC、および最初のトラックのプリギャップのみが消去されます。ディスクを短時間で消去できますが (レコーダーの速度に応じて 1 分から 2 分程度)、プログラム領域にはユーザーデータが残ります。一方、フル消去ではディスク全体が消去されます。

vtbl 17 HRESULT Close()

ディスクレコーダーへの排他アクセスを解放します。これにより、ドライブへのファイルシステムアクセスが復元されます。

戻り値

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IDiscRecorder "{85AC9776-CA88-4CF2-894E-09598C078A41}"
#usecom global IDiscRecorder IID_IDiscRecorder "{}"
#comfunc global IDiscRecorder_Init                   3 var,int,int
#comfunc global IDiscRecorder_GetRecorderGUID        4 var,int,var
#comfunc global IDiscRecorder_GetRecorderType        5 var
#comfunc global IDiscRecorder_GetDisplayNames        6 var,var,var
#comfunc global IDiscRecorder_GetBasePnPID           7 var
#comfunc global IDiscRecorder_GetPath                8 var
#comfunc global IDiscRecorder_GetRecorderProperties  9 sptr
#comfunc global IDiscRecorder_SetRecorderProperties  10 sptr
#comfunc global IDiscRecorder_GetRecorderState       11 var
#comfunc global IDiscRecorder_OpenExclusive          12
#comfunc global IDiscRecorder_QueryMediaType         13 var,var
#comfunc global IDiscRecorder_QueryMediaInfo         14 var,var,var,var,var
#comfunc global IDiscRecorder_Eject                  15
#comfunc global IDiscRecorder_Erase                  16 int
#comfunc global IDiscRecorder_Close                  17
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IDiscRecorder "{85AC9776-CA88-4CF2-894E-09598C078A41}"
#usecom global IDiscRecorder IID_IDiscRecorder "{}"
#comfunc global IDiscRecorder_Init                   3 sptr,int,int
#comfunc global IDiscRecorder_GetRecorderGUID        4 sptr,int,sptr
#comfunc global IDiscRecorder_GetRecorderType        5 sptr
#comfunc global IDiscRecorder_GetDisplayNames        6 sptr,sptr,sptr
#comfunc global IDiscRecorder_GetBasePnPID           7 sptr
#comfunc global IDiscRecorder_GetPath                8 sptr
#comfunc global IDiscRecorder_GetRecorderProperties  9 sptr
#comfunc global IDiscRecorder_SetRecorderProperties  10 sptr
#comfunc global IDiscRecorder_GetRecorderState       11 sptr
#comfunc global IDiscRecorder_OpenExclusive          12
#comfunc global IDiscRecorder_QueryMediaType         13 sptr,sptr
#comfunc global IDiscRecorder_QueryMediaInfo         14 sptr,sptr,sptr,sptr,sptr
#comfunc global IDiscRecorder_Eject                  15
#comfunc global IDiscRecorder_Erase                  16 int
#comfunc global IDiscRecorder_Close                  17
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。