同期デバイス入出力

このページでは、USBデバイス入出力用のlibusbの同期(ブロッキング)APIについて説明します。このインターフェイスンは使いやすいですが、いくつかの制限があります。上級ユーザーは、代わりに 非同期入出力API の使用を検討することをお勧めします。 さらに…

関数
int	libusb_control_transfer (libusb_device_handle *dev_handle, uint8_t bmRequestType, uint8_t bRequest, uint16_t wValue, uint16_t wIndex, unsigned char *data, uint16_t wLength, unsigned int timeout)
int	libusb_bulk_transfer (libusb_device_handle *dev_handle, unsigned char endpoint, unsigned char *data, int length, int *transferred, unsigned int timeout)
int	libusb_interrupt_transfer (libusb_device_handle *dev_handle, unsigned char endpoint, unsigned char *data, int length, int *transferred, unsigned int timeout)

詳細説明

このページでは、USBデバイス入出力用のlibusbの同期(ブロッキング)APIについて説明します。このインターフェイスンは使いやすいですが、いくつかの制限があります。上級ユーザーは、代わりに 非同期入出力API の使用を検討することをお勧めします。

関数解説

libusb_control_transfer()

int libusb_control_transfer	(	libusb_device_handle *	dev_handle,
		uint8_t	bmRequestType,
		uint8_t	bRequest,
		uint16_t	wValue,
		uint16_t	wIndex,
		unsigned char *	data,
		uint16_t	wLength,
		unsigned int	timeout
	)

USB制御転送を実行します。

転送の方向は、セットアップ・パケットのbmRequestTypeフィールドから推測されます。

wValueとwIndexとwLengthフィールドの値は、ホスト・エンディアンのバイト順序で指定する必要があります。

パラメーター

dev_handle	デバイスが通信するためのハンドル
bmRequestType	セットアップ・パケットの要求タイプ・フィールド
bRequest	セットアップ・パケットの要求フィールド
wValue	セットアップ・パケットの値フィールド
wIndex	セットアップ・パケットのインデックス(index)フィールド
data	入力または出力のいずれかに適したサイズのデータ・バッファ(bmRequestType内の方向ビットに応じて)
wLength	セットアップ・パケットの長さフィールド。データ・バッファは最低このサイズである必要があります。
timeout	応答が受信できない間、この関数が諦めるまでに待機するタイムアウト(ミリ秒単位)。無期限のタイムアウトには、値0を使用します。

戻り値

成功した場合は実際に転送されたバイト数

LIBUSB_ERROR_TIMEOUT 転送タイムアウトの場合

LIBUSB_ERROR_PIPE 制御要求がデバイスでサポートされていない場合

LIBUSB_ERROR_NO_DEVICE デバイスが切断されている場合

LIBUSB_ERROR_BUSY イベント処理コンテキストから呼び出された場合

LIBUSB_ERROR_INVALID_PARAM 転送サイズがオペレーティング・システムやハードウェアでサポートできるサイズよりも大きい場合 ( 転送長さ制限 を参照して下さい)

LIBUSB_ERROR その他失敗

libusb_bulk_transfer()

int libusb_bulk_transfer	(	libusb_device_handle *	dev_handle,
		unsigned char	endpoint,
		unsigned char *	data,
		int	length,
		int *	transferred,
		unsigned int	timeout
	)

USBバルク送を実行します。転送の方向は、エンドポイント・アドレスの方向ビットから推測されます。

バルクみ取りの場合、 length フィールドは、受信する予定のデータの最大長を示します。予想よりも少ないデータが到着した場合、この関数はその実際のデータを返すため、 transfered 出力パラメーターを必ず確認してください。

バルク書き込みについては、transfered パラメーターも確認する必要があります。すべてのデータが書き込まれているとは限りません

タイムアウト・エラー・コードを処理するときは、 transferedも確認してください。 libusbは、基になるOSの要件を満たすために、転送をいくつかのチャンクに分割する必要がある場合があります。つまり、最初のいくつかのチャンクが完了した後にタイムアウトが期限切れになる場合があります。libusbは、転送された可能性のあるデータを失わないように注意しています。タイムアウト状態が入出力の完全な失敗を示していると想定しないでください。詳細については、 タイムアウト を参照してください。

パラメーター

dev_handle	デバイスが通信するためのハンドル
endpoint	通信したい有効なエンドポイントのアドレス
data	(エンドポイントに応じた)入力または出力のいずれかに適したサイズのデータ・バッファ
length	バルク書き込みの場合、送信したいデータのバイト数。バルク読み取りの場合、データ・バッファに受信する最大バイト数。
transferred	実際に転送されたバイト数の出力場所。バージョン 1.0.21 以降(LIBUSB_API_VERSION >= 0x01000105)、この情報を受け取りたくない場合はNULLポインタを渡すことができます。
timeout	応答が受信できない間、この関数が諦めるまでに待機するタイムアウト(ミリ秒単位)。無期限のタイムアウトには、値0を使用します。

戻り値

0ならば成功(そして成功ならば、 transferred の示す場所に値が入力されています)

LIBUSB_ERROR_TIMEOUT ならば転送タイムアウト(かつ、 transferred の示す場所に値が入力されています)

LIBUSB_ERROR_PIPE そのエンドポイントは停止(halt)状態

LIBUSB_ERROR_OVERFLOW デバイスが想定より多くのデータを提供した場合。 パケットとオーバーフロー を参照して下さい

LIBUSB_ERROR_NO_DEVICE デバイスが切断されている場合

LIBUSB_ERROR_BUSY イベント処理コンテキストから呼び出された場合

LIBUSB_ERROR_INVALID_PARAM 転送サイズがオペレーティング・システムやハードウェアでサポートできるサイズよりも大きい場合 ( 転送長さ制限 を参照して下さい)

LIBUSB_ERROR その他失敗

libusb_interrupt_transfer()

int libusb_interrupt_transfer	(	libusb_device_handle *	dev_handle,
		unsigned char	endpoint,
		unsigned char *	data,
		int	length,
		int *	transferred,
		unsigned int	timeout
	)

USB割り込み転送を実行します。転送の方向は、エンドポイント・アドレスの方向ビットから推測されます。

割り込み読み取りの場合、 lengthフィールドは、受信する予定のデータの最大長を示します。予想よりも少ないデータが到着した場合、この関数はその実際のデータを返すため、 transfered 出力パラメーターを必ず確認してください。

割り込み書き込みについては、 transfered パラメーターも確認する必要があります。すべてのデータが書き込まれている保証はありません。

タイムアウト・エラー・コードを処理するときは、 transferedも確認してください。 libusbは、基になるOSの要件を満たすために、転送をいくつかのチャンクに分割する必要がある場合があります。つまり、最初のいくつかのチャンクが完了した後にタイムアウトが期限切れになる場合があります。libusbは、転送された可能性のあるデータを失わないように注意しています。タイムアウト状態が入出力の完全な失敗を示していると想定しないでください。詳細については、 タイムアウト を参照してください。

デフォルトのエンドポイントのbInterval値がポーリング間隔として使用されます。

パラメーター

dev_handle	デバイスが通信するためのハンドル
endpoint	通信したい有効なエンドポイントのアドレス
data	(エンドポイントに応じた)入力または出力のいずれかに適したサイズのデータ・バッファ
length	バルク書き込みの場合、送信したいデータのバイト数。バルク読み取りの場合、データ・バッファに受信する最大バイト数。
transferred	実際に転送されたバイト数の出力場所。バージョン 1.0.21 以降(LIBUSB_API_VERSION >= 0x01000105)、この情報を受け取りたくない場合はNULLポインタを渡すことができます。
timeout	応答が受信できない間、この関数が諦めるまでに待機するタイムアウト(ミリ秒単位)。無期限のタイムアウトには、値0を使用します。

戻り値

0ならば成功(そして成功ならば、 transferred の示す場所に値が入力されています)

LIBUSB_ERROR_TIMEOUT 転送タイムアウトの場合

LIBUSB_ERROR_PIPE そのエンドポイントは停止(halt)状態

LIBUSB_ERROR_OVERFLOW デバイスが想定より多くのデータを提供した場合。 パケットとオーバーフロー を参照して下さい

LIBUSB_ERROR_NO_DEVICE デバイスが切断されている場合

LIBUSB_ERROR_BUSY イベント処理コンテキストから呼び出された場合

LIBUSB_ERROR_INVALID_PARAM 転送サイズがオペレーティング・システムやハードウェアでサポートできるサイズよりも大きい場合 ( 転送長さ制限 を参照して下さい)

LIBUSB_ERROR その他のエラー