第 2 章:USBX 主机类 API

本章介绍 USBX 主机类的所有公开的 API。 详细介绍了以下每个类的 API。

  • 打印机类
  • 音频类
  • Asix 类
  • Pima/PTP 类
  • Prolific 类
  • 通用序列类

ux_host_class_printer_read

从打印机接口读取。

原型

UINT ux_host_class_printer_read(
    UX_HOST_CLASS_PRINTER *printer,
    UCHAR *data_pointer,
    ULONG requested_length,
    ULONG *actual_length)

说明

此函数从打印机接口读取。 调用阻塞,仅在出现错误或传输完成时返回。 只允许在双向打印机上进行读取。

参数

  • printer:指向打印机类实例的指针。
  • data_pointer:指向数据有效负载的缓冲区地址的指针。
  • requested_length:要接收的长度。
  • actual_length:实际接收的长度。

返回值

  • UX_SUCCESS:(0x00) 已完成数据传输。
  • UX_FUNCTION_NOT_SUPPORTED:(0x54) 函数不受支持,因为打印机不是双向的。
  • UX_TRANSFER_TIMEOUT:(0x5c) 传输超时,读取未完成。

示例

UINT status;

/* The following example illustrates this service. */
status = ux_host_class_printer_read(printer, data_pointer, requested_length, &actual_length);

/* If status equals UX_SUCCESS, the operation was successful. */

ux_host_class_printer_write

写入打印机接口。

原型

UINT ux_host_class_printer_write(
    UX_HOST_CLASS_PRINTER *printer,
    UCHAR *data_pointer,  
    ULONG requested_length,
    ULONG *actual_length)

说明

此函数写入打印机接口。 调用阻塞,仅在出现错误或传输完成时返回。

参数

  • printer:指向打印机类实例的指针。
  • data_pointer:指向数据有效负载的缓冲区地址的指针。
  • requested_length:要发送的长度。
  • actual_length:实际发送的长度。

返回值

  • UX_SUCCESS:(0x00) 已完成数据传输。
  • UX_TRANSFER_TIMEOUT:(0x5c) 传输超时,写入未完成。

示例

UINT status;

/* The following example illustrates this service. */
status = ux_host_class_printer_write(printer, data_pointer, requested_length, &actual_length);

/* If status equals UX_SUCCESS, the operation was successful. */

ux_host_class_printer_soft_reset

对打印机执行软重置。

原型

UINT ux_host_class_printer_soft_reset(UX_HOST_CLASS_PRINTER *printer)

说明

此函数对打印机执行软重置。

输入参数

  • printer:指向打印机类实例的指针。

返回值

  • UX_SUCCESS:(0x00) 已完成重置。
  • UX_TRANSFER_TIMEOUT:(0x5c) 传输超时,重置未完成。

示例

UINT status;

/* The following example illustrates this service. */
status = ux_host_class_printer_soft_reset(printer);

/* If status equals UX_SUCCESS, the operation was successful. */

ux_host_class_printer_status_get

获取打印机状态

原型

UINT ux_host_class_printer_status_get( 
    UX_HOST_CLASS_PRINTER *printer,
    ULONG *printer_status)

说明

此函数获取打印机状态。 打印机状态类似于 LPT 状态(1284 标准)。

参数

  • printer:指向打印机类实例的指针。
  • printer_status:要返回的状态的地址。

返回值

  • UX_SUCCESS (0x00):已完成重置。
  • UX_MEMORY_INSUFFICIENT:(0x12) 内存不足,无法执行该操作。
  • UX_TRANSFER_TIMEOUT:(0x5c) 传输超时,重置未完成

示例

UINT status;

/* The following example illustrates this service. */
status = ux_host_class_printer_status_get(printer, printer_status);

/* If status equals UX_SUCCESS, the operation was successful. */

ux_host_class_printer_device_id_get

获取打印机设备 ID。

原型

UINT ux_host_class_printer_device_id_get( 
    UX_HOST_CLASS_PRINTER *printer,
    UCHAR *descriptor_buffer, 
    ULONG length)

说明

此函数获取打印机 IEEE 1284 设备 ID 字符串(包括 big endian 格式前两个字节的长度)。

参数

  • printer:指向打印机类实例的指针。
  • descriptor_buffer:指向用于填充 IEEE 1284 设备 ID 字符串(包括 BE 格式前两个字节的长度)的缓冲区的指针
  • length:缓冲区的长度(以字节为单位)。

返回值

  • UX_SUCCESS (0x00):操作成功。
  • UX_MEMORY_INSUFFICIENT:(0x12) 内存不足,无法执行该操作。
  • UX_TRANSFER_TIMEOUT:(0x5c) 传输超时,请求未完成
  • UX_TRANSFER_NOT_READY:(0x25) 设备处于无效状态 - 状态必须为 ATTACHED、ADDRESSED 或 CONFIGURED。
  • UX_TRANSFER_STALL:(0x21) 传输停滞。
  • TX_WAIT_ABORTED:(0x1A) 挂起状态由其他线程、计时器或 ISR 中止。
  • TX_SEMAPHORE_ERROR:(0x0C) 计数信号灯指针无效。
  • TX_WAIT_ERROR:(0x04) 在非线程的调用上指定了除 TX_NO_WAIT 以外的等待选项。

示例

UINT status;

/* The following example illustrates this service. */
status = ux_host_class_printer_device_id_get(printer, descriptor_buffer, length);

/* If status equals UX_SUCCESS, the operation was successful. */

ux_host_class_audio_read

从音频接口读取。

原型

UINT ux_host_class_audio_read(
    UX_HOST_CLASS_AUDIO *audio,
    UX_HOST_CLASS_AUDIO_TRANSFER_REQUEST
    *audio_transfer_request)

说明

此函数从音频接口读取。 调用为非阻塞。 应用程序必须确保为音频流式处理接口选择了适当的备用设置。

参数

  • audio:指向音频类实例的指针。
  • audio_transfer_request:指向音频传输结构的指针。

返回值

  • UX_SUCCESS:(0x00) 已完成数据传输
  • UX_FUNCTION_NOT_SUPPORTED:(0x54) 函数不受支持

示例

/* The following example reads from the audio interface. */

audio_transfer_request.ux_host_class_audio_transfer_request_completion_function = tx_audio_transfer_completion_function;
audio_transfer_request.ux_host_class_audio_transfer_request_class_instance = audio;
audio_transfer_request.ux_host_class_audio_transfer_request_next_audio_audio_transfer_request = UX_NULL;
audio_transfer_request.ux_host_class_audio_transfer_request_data_pointer = audio_buffer;
audio_transfer_request.ux_host_class_audio_transfer_request_requested_length = requested_length;
audio_transfer_request.ux_host_class_audio_transfer_request_packet_length = AUDIO_FRAME_LENGTH;

status = ux_host_class_audio_read(audio, audio_transfer_request);

/* If status equals UX_SUCCESS, the operation was successful. */

ux_host_class_audio_write

写入音频接口。

原型

UINT ux_host_class_audio_write(
    UX_HOST_CLASS_AUDIO *audio,
    UX_HOST_CLASS_AUDIO_TRANSFER_REQUEST *audio_transfer_request)

说明

此函数写入音频接口。 调用为非阻塞。 应用程序必须确保为音频流式处理接口选择了适当的备用设置。

参数

  • audio:指向音频类实例的指针
  • audio_transfer_request:指向音频传输结构的指针

返回值

  • UX_SUCCESS:(0x00) 已完成数据传输。
  • UX_FUNCTION_NOT_SUPPORTED:(0x54) 函数不受支持。
  • ux_host_CLASS_AUDIO_WRONG_INTERFACE:(0x81) 接口不正确。

示例

UINT status;

/* The following example writes to the audio interface */

audio_transfer_request.ux_host_class_audio_transfer_request_completion_function = tx_audio_transfer_completion_function;
audio_transfer_request.ux_host_class_audio_transfer_request_class_instance = audio;
audio_transfer_request.ux_host_class_audio_transfer_request_next_audio_audio_transfer_request = UX_NULL;
audio_transfer_request.ux_host_class_audio_transfer_request_data_pointer = audio_buffer;
audio_transfer_request.ux_host_class_audio_transfer_request_requested_length = requested_length;
audio_transfer_request.ux_host_class_audio_transfer_request_packet_length = AUDIO_FRAME_LENGTH;
status = ux_host_class_audio_write(audio, audio_transfer_request);

/* If status equals UX_SUCCESS, the operation was successful. */

ux_host_class_audio_control_get

从音频控件接口获取特定控件。

原型

UINT ux_host_class_audio_control_get(
    UX_HOST_CLASS_AUDIO *audio,
    UX_HOST_CLASS_AUDIO_CONTROL *audio_control)

说明

此函数从音频控件接口读取特定控件。

参数

  • audio:指向音频类实例的指针
  • audio_control:指向音频控件结构的指针

返回值

  • UX_SUCCESS:(0x00) 已完成数据传输
  • UX_FUNCTION_NOT_SUPPORTED:(0x54) 函数不受支持
  • UX_HOST_CLASS_AUDIO_WRONG_INTERFACE:(0x81) 接口不正确

示例

UINT status;

/* The following example reads the volume control from a stereo USB speaker. */

UX_HOST_CLASS_AUDIO_CONTROL audio_control;

audio_control.ux_host_class_audio_control_channel = 1;
audio_control.ux_host_class_audio_control = UX_HOST_CLASS_AUDIO_VOLUME_CONTROL;

status = ux_host_class_audio_control_get(audio, &audio_control);

/* If status equals UX_SUCCESS, the operation was successful. */

audio_control.ux_host_class_audio_control_channel = 2;
audio_control.ux_host_class_audio_control = UX_HOST_CLASS_AUDIO_VOLUME_CONTROL;

status = ux_host_class_audio_control_get(audio, &audio_control);

/* If status equals UX_SUCCESS, the operation was successful. */

ux_host_class_audio_control_value_set

为音频控件接口设置特定的控件。

原型

UINT ux_host_class_audio_control_value_set(
    UX_HOST_CLASS_AUDIO *audio,
    UX_HOST_CLASS_AUDIO_CONTROL *audio_control)

**说明 **

此函数为音频控件接口设置特定的控件。

参数

  • audio:指向音频类实例的指针
  • audio_control:指向音频控件结构的指针

返回值

  • UX_SUCCESS:(0x00) 已完成数据传输
  • UX_FUNCTION_NOT_SUPPORTED:(0x54) 函数不受支持
  • UX_HOST_CLASS_AUDIO_WRONG_INTERFACE:(0x81) 接口不正确

示例

/* The following example sets the volume control of a stereo USB speaker. */

UX_HOST_CLASS_AUDIO_CONTROL audio_control;

UINT status;

audio_control.ux_host_class_audio_control_channel = 1;
audio_control.ux_host_class_audio_control = UX_HOST_CLASS_AUDIO_VOLUME_CONTROL;
audio_control.ux_host_class_audio_control_cur = 0xf000;

status = ux_host_class_audio_control_value_set(audio, &audio_control);
/* If status equals UX_SUCCESS, the operation was successful. */

current_volume = audio_control.audio_control_cur;
audio_control.ux_host_class_audio_control_channel = 2;
audio_control.ux_host_class_audio_control = UX_HOST_CLASS_AUDIO_VOLUME_CONTROL;
audio_control.ux_host_class_audio_control_cur = 0xf000;

status = ux_host_class_audio_control_value_set(audio, &audio_control);
/* If status equals UX_SUCCESS, the operation was successful. */

ux_host_class_audio_streaming_sampling_set

设置音频流式处理接口的备用设置接口。

原型

UINT ux_host_class_audio_streaming_sampling_set
    (UX_HOST_CLASS_AUDIO *audio,
    UX_HOST_CLASS_AUDIO_SAMPLING *audio_sampling)

说明

此函数根据特定采样结构设置音频流式处理接口的适当备用设置接口。

参数

  • audio:指向音频类实例的指针。
  • audio_sampling:指向音频采样结构的指针。

返回值

  • UX_SUCCESS:(0x00) 已完成数据传输
  • UX_FUNCTION_NOT_SUPPORTED:(0x54) 函数不受支持
  • UX_HOST_CLASS_AUDIO_WRONG_INTERFACE:(0x81) 接口不正确
  • UX_NO_ALTERNATE_SETTING:(0x5e) 采样值没有备用设置

示例

/* The following example sets the alternate setting interface of a stereo USB speaker. */

UX_HOST_CLASS_AUDIO_SAMPLING audio_sampling;

UINT status;

sampling.ux_host_class_audio_sampling_channels = 2;
sampling.ux_host_class_audio_sampling_frequency = AUDIO_FREQUENCY;
sampling. ux_host_class_audio_sampling_resolution = 16;

status = ux_host_class_audio_streaming_sampling_set(audio, &sampling);
/* If status equals UX_SUCCESS, the operation was successful. */

ux_host_class_audio_streaming_sampling_get

获取音频流式处理接口的可能采样设置。

原型

UINT ux_host_class_audio_streaming_sampling_get(
    UX_HOST_CLASS_AUDIO *audio,
    UX_HOST_CLASS_AUDIO_SAMPLING_CHARACTERISTICS *audio_sampling)

说明

此函数逐个获取可在音频流式处理接口的每个备用设置中使用的所有可能的采样设置。 第一次使用函数时,必须重置调用结构指针中的所有字段。 此函数将在返回时返回一组特定的流式处理值,除非已达到替代设置的结尾。 重用此函数时,将使用之前的采样值来查找下一采样值。

参数

  • audio:指向音频类实例的指针。
  • audio_sampling:指向音频采样结构的指针。

返回值

  • UX_SUCCESS:(0x00) 已完成数据传输
  • UX_FUNCTION_NOT_SUPPORTED:(0x54) 函数不受支持
  • UX_HOST_CLASS_AUDIO_WRONG_INTERFACE:(0x81) 接口不正确
  • UX_NO_ALTERNATE_SETTING:(0x5e) 采样值没有备用设置

示例

/* The following example gets the sampling values for the first alternate setting interface of a stereo USB speaker. */

UX_HOST_CLASS_AUDIO_SAMPLING_CHARACTERISTICS audio_sampling;

UINT status;

sampling.ux_host_class_audio_sampling_channels=0;
sampling.ux_host_class_audio_sampling_frequency_low=0;
sampling.ux_host_class_audio_sampling_frequency_high=0;
sampling.ux_host_class_audio_sampling_resolution=0;

status = ux_host_class_audio_streaming_sampling_get(audio, &sampling);

/* If status equals UX_SUCCESS, the operation was successful and information could be displayed as follows:

printf("Number of channels %d, Resolution %d bits, frequency range %d-%d\n",
    sampling.audio_channels, sampling.audio_resolution,
    sampling.audio_frequency_low, sampling.audio_frequency_high);

*/

ux_host_class_asix_read

从 asix 接口读取。

原型

UINT ux_host_class_asix_read(
    UX_HOST_CLASS_ASIX *asix,
    UCHAR *data_pointer,
    ULONG requested_length,
    ULONG *actual_length)

说明

此函数从 asix 接口读取。 调用阻塞,仅在出现错误或传输完成时返回。

参数

  • asix:指向 asix 类实例的指针。
  • data_pointer:指向数据有效负载的缓冲区地址的指针。
  • requested_length:要接收的长度。
  • actual_length:实际接收的长度。

返回值

  • UX_SUCCESS:(0x00) 已完成数据传输。
  • UX_TRANSFER_TIMEOUT:(0x5c) 传输超时,读取未完成。

示例

UINT status;

/* The following example illustrates this service. */

status = ux_host_class_asix_read(asix, data_pointer, requested_length, &actual_length);

/* If status equals UX_SUCCESS, the operation was successful. */

ux_host_class_asix_write

写入 asix 接口。

原型

UINT ux_host_class_asix_write(
    VOID *asix_class,
    NX_PACKET *packet)

说明

此函数写入 asix 接口。 调用为非阻塞。

参数

  • asix:指向 asix 类实例的指针。
  • packet:Netx 数据包

返回值

  • UX_SUCCESS:(0x00) 已完成数据传输。
  • UX_ERROR:(0xFF) 无法请求传输。

示例

UINT status;

/* The following example illustrates this service. */

status = ux_host_class_asix_write(asix, packet);

/* If status equals UX_SUCCESS, the operation was successful. */

ux_host_class_pima_session_open

在发起方和响应方之间打开会话。

原型

UINT ux_host_class_pima_session_open(
    UX_HOST_CLASS_PIMA *pima,
    UX_HOST_CLASS_PIMA_SESSION *pima_session)

说明

此函数在 PIMA 发起方和 PIMA 响应方之间打开一个会话。 成功打开会话后,可以执行大多数 PIMA 命令。

参数

  • pima:指向 PIMA 类实例的指针。
  • pima_session:指向 PIMA 会话的指针<

返回值

  • UX_SUCCESS:(0x00) 会话已成功打开
  • UX_HOST_CLASS_PIMA_RC_SESSION_ALREADY_OPENED:(0x201E) 会话已打开

示例

/* Open a pima session. */

status = ux_host_class_pima_session_open(pima, pima_session);

if (status != UX_SUCCESS)
    return(UX_PICTBRIDGE_ERROR_SESSION_NOT_OPEN);

ux_host_class_pima_session_close

在发起方和响应方之间关闭会话。

原型

UINT ux_host_class_pima_session_close(
    UX_HOST_CLASS_PIMA *pima,
    UX_HOST_CLASS_PIMA_SESSION *pima_session)

说明

此函数关闭之前在 PIMA 发起方和 PIMA 响应方之间打开的会话。 会话关闭后,将无法再执行大多数 PIMA 命令。

参数

  • pima:指向 pima 类实例的指针。
  • pima_session:指向 PIMA 会话的指针。

返回值

  • UX_SUCCESS:(0x00) 会话已关闭。
  • UX_HOST_CLASS_PIMA_RC_SESSION_NOT_OPEN:(0x2003) 会话未打开。

示例

/* Close the pima session. */

status = ux_host_class_pima_session_close(pima, pima_session);

ux_host_class_pima_storage_ids_get

从响应方获取存储 ID 数组。

原型

UINT ux_host_class_pima_storage_ids_get(
    UX_HOST_CLASS_PIMA *pima,
    UX_HOST_CLASS_PIMA_SESSION *pima_session,
    ULONG *storage_ids_array,
    ULONG storage_id_length)

说明

此函数从响应方获取存储 ID 数组。

参数

  • pima:指向 pima 类实例的指针。
  • pima_session:指向 PIMA 会话的指针
  • storage_ids_array:将在其中返回存储 ID 的数组
  • storage_id_length:存储阵列的长度

返回值

  • UX_SUCCESS:(0x00) 已填充存储 ID 数组
  • UX_HOST_CLASS_PIMA_RC_SESSION_NOT_OPEN:(0x2003) 会话未打开
  • UX_MEMORY_INSUFFICIENT:(0x12) 内存不足,无法创建 PIMA 命令。

示例

/* Get the number of storage IDs. */
status = ux_host_class_pima_storage_ids_get(pima, pima_session,
    pictbridge ->ux_pictbridge_storage_ids, 64);

if (status != UX_SUCCESS)
{
    /* Close the pima session. */
    status = ux_host_class_pima_session_close(pima, pima_session);

    return(UX_PICTBRIDGE_ERROR_STORE_NOT_AVAILABLE);
}

ux_host_class_pima_storage_info_get

从响应方获取存储信息。

原型

UINT ux_host_class_pima_storage_info_get(
    UX_HOST_CLASS_PIMA *pima,
    UX_HOST_CLASS_PIMA_SESSION *pima_session,
    ULONG storage_id,
    UX_HOST_CLASS_PIMA_STORAGE *storage)

说明

此函数获取值为 storage_id 的存储容器的存储信息。

参数

  • pima:指向 pima 类实例的指针。
  • pima_session:指向 PIMA 会话的指针
  • storage_id:存储容器的 ID
  • 存储:指向存储信息容器的指针

返回值

  • UX_SUCCESS:(0x00) 已检索存储信息
  • UX_HOST_CLASS_PIMA_RC_SESSION_NOT_OPEN:(0x2003) 会话未打开
  • UX_MEMORY_INSUFFICIENT (0x12) 内存不足,无法创建 PIMA 命令。

示例

/* Get the first storage ID info container. */
status = ux_host_class_pima_storage_info_get(pima, pima_session,
    pictbridge ->ux_pictbridge_storage_ids[0],
    (UX_HOST_CLASS_PIMA_STORAGE *)pictbridge ->ux_pictbridge_storage);

if (status != UX_SUCCESS)
{
    /* Close the pima session. */
    status = ux_host_class_pima_session_close(pictbridge ->
        ux_pictbridge_pima, pima_session);
    return(UX_PICTBRIDGE_ERROR_STORE_NOT_AVAILABLE);
}

ux_host_class_pima_num_objects_get

从响应方获取存储容器上的对象数。

原型

UINT ux_host_class_pima_num_objects_get(
    UX_HOST_CLASS_PIMA *pima,
    UX_HOST_CLASS_PIMA_SESSION *pima_session,
    ULONG storage_id,
    ULONG object_format_code)

说明

此函数获取与特定格式代码匹配且值为 storage_id 的特定存储容器中存储的对象数。 对象数在 ux_host_class_pima_session_nb_objects of the pima_session structure 字段中返回。

参数

  • pima:指向 pima 类实例的指针。
  • pima_session:指向 PIMA 会话的指针
  • storage_id:存储容器的 ID
  • object_format_code:对象格式代码筛选器。

对象格式代码可以有以下值之一。

对象格式代码 说明 USBX 代码
0x3000 未定义的非图像对象 UX_HOST_CLASS_PIMA_OFC_UNDEFINED
0x3001 关联(如文件夹) UX_HOST_CLASS_PIMA_OFC_ASSOCIATION
0x3002 特定于脚本设备模型的脚本 UX_HOST_CLASS_PIMA_OFC_SCRIPT
0x3003 特定于可执行设备模型的二进制可执行文件 UX_HOST_CLASS_PIMA_OFC_EXECUTABLE
0x3004 文本文件 UX_HOST_CLASS_PIMA_OFC_TEXT
0x3005 HTML 超文本标记语言文件(文本) UX_HOST_CLASS_PIMA_OFC_HTML
0x3006 DPOF 数码打印命令格式文件(文本) UX_HOST_CLASS_PIMA_OFC_DPOF
0x3007 AIFF 音频剪辑 UX_HOST_CLASS_PIMA_OFC_AIFF
0x3008 WAV 音频剪辑 UX_HOST_CLASS_PIMA_OFC_WAV
0x3009 MP3 音频剪辑 UX_HOST_CLASS_PIMA_OFC_MP3
0x300A AVI 视频剪辑 UX_HOST_CLASS_PIMA_OFC_AVI
0x300B MPEG 视频剪辑 UX_HOST_CLASS_PIMA_OFC_MPEG
0x300C ASF Microsoft 高级流式处理格式(视频) UX_HOST_CLASS_PIMA_OFC_ASF
0x3800 未定义的未知图像对象 UX_HOST_CLASS_PIMA_OFC_QT
0x3801 EXIF/JPEG 可交换文件格式,JEIDA 标准 UX_HOST_CLASS_PIMA_OFC_EXIF_JPEG
0x3802 TIFF/EP 适用于电子摄影的标记图像文件格式 UX_HOST_CLASS_PIMA_OFC_TIFF_EP
0x3803 FlashPix 结构化存储图像格式 UX_HOST_CLASS_PIMA_OFC_FLASHPIX
0x3804 BMP Microsoft Windows 位图文件 UX_HOST_CLASS_PIMA_OFC_BMP
0x3805 CIFF Canon 相机图像文件格式 UX_HOST_CLASS_PIMA_OFC_CIFF
0x3806 未定义的保留
0x3807 GIF 图形交换格式 UX_HOST_CLASS_PIMA_OFC_GIF
0x3808 JFIF JPEG 文件交换格式 UX_HOST_CLASS_PIMA_OFC_JFIF
0x3809 PCD PhotoCD 图像 Pac UX_HOST_CLASS_PIMA_OFC_PCD
0x380A PICT Quickdraw 图像格式 UX_HOST_CLASS_PIMA_OFC_PICT
0x380B PNG 可移植网络图形格式 UX_HOST_CLASS_PIMA_OFC_PNG
0x380C 未定义的保留
0x380D TIFF 标记图像文件格式 UX_HOST_CLASS_PIMA_OFC_TIFF
0x380E TIFF/IT 适用于信息技术(图形艺术)的标记图像文件格式 UX_HOST_CLASS_PIMA_OFC_TIFF_IT
0x380F JP2 JPEG2000 基线文件格式 UX_HOST_CLASS_PIMA_OFC_JP2
0x3810 JPX JPEG2000 扩展文件格式 UX_HOST_CLASS_PIMA_OFC_JPX
MSN 0011 的所有其他代码 任何未定义的保留以供将来使用
MSN 1011 的所有其他代码 供应商定义的任何类型:图像

返回值

  • UX_SUCCESS:(0x00) 已完成数据传输。
  • UX_HOST_CLASS_PIMA_RC_SESSION_NOT_OPEN:(0x2003) 会话未打开
  • UX_MEMORY_INSUFFICIENT:(0x12) 内存不足,无法创建 PIMA 命令。

示例

/* Get the number of objects on all containers matching a SCRIPT object. */
status = ux_host_class_pima_num_objects_get(pima, pima_session,
    UX_PICTBRIDGE_ALL_CONTAINERS, UX_PICTBRIDGE_OBJECT_SCRIPT);

if (status != UX_SUCCESS)
{
    /* Close the pima session. */
    status = ux_**host_class_pima_session_close(pima, pima_session);

    return(UX_PICTBRIDGE_ERROR_STORE_NOT_AVAILABLE);
} else
    /* The number of objects is returned in the field: pima_session -> ux_host_class_pima_session_nb_objects */

ux_host_class_pima_object_handles_get

从响应方获取对象句柄。

原型

UINT ux_host_class_pima_object_handles_get(
    UX_HOST_CLASS_PIMA *pima,
    UX_HOST_CLASS_PIMA_SESSION *pima_session,
    ULONG *object_handles_array,
    ULONG object_handles_length,
    ULONG storage_id,
    ULONG object_format_code,
    ULONG object_handle_association)

说明

返回由 storage_id 参数指示的存储容器中存在的对象句柄的数组。 如果需要跨所有存储的聚合列表,则此值应设置为 0xFFFFFFFF。

参数

  • pima:指向 pima 类实例的指针。
  • pima_session:指向 PIMA 会话的指针
  • object_handes_array:在其中返回句柄的数组
  • object_handles_length:数组的长度
  • storage_id:存储容器的 ID
  • object_format_code:对象的格式代码(请参阅函数 ux_host_class_pima_num_objects_get 的表)
  • object_handle_association:可选对象关联值

对象句柄关联可以是下表中的值之一:

关联代码 关联类型 解释
0x0000 Undefined Undefined
0x0001 GenericFolder 未使用
0x0002 相册: 保留
0x0003 TimeSequence DefaultPlaybackDelta
0x0004 HorizontalPanoramic 未使用
0x0005 VerticalPanoramic 未使用
0x0006 2DPanoramic ImagesPerRow
0x0007 AncillaryData Undefined
位 15 设置为 0 的所有其他值 保留 Undefined
位 15 设置为 1 的所有值 供应商定义 供应商定义

返回值

  • UX_SUCCESS:(0x00) 已完成数据传输。
  • UX_HOST_CLASS_PIMA_RC_SESSION_NOT_OPEN:(0x2003) 会话未打开
  • UX_MEMORY_INSUFFICIENT:(0x12) 内存不足,无法创建 PIMA 命令。

示例

/* Get the array of objects handles on the container. */
status = ux_**host_class_pima_object_handles_get(pima, pima_session,
    pictbridge ->ux_pictbridge_object_handles_array,
    4 * pima_session ->ux_host_class_pima_session_nb_objects,
    UX_PICTBRIDGE_ALL_CONTAINERS,
    UX_PICTBRIDGE_OBJECT_SCRIPT, 0);

if (status != UX_SUCCESS)
{
    /* Close the pima session. */
    status = ux_host_class_pima_session_close(pima, pima_session);
    return(UX_PICTBRIDGE_ERROR_STORE_NOT_AVAILABLE);
}

ux_host_class_pima_object_info_get

从响应方获取对象信息。

原型

UINT ux_host_class_pima_object_info_get(
    UX_HOST_CLASS_PIMA *pima,
    UX_HOST_CLASS_PIMA_SESSION *pima_session,
    ULONG object_handle,
    UX_HOST_CLASS_PIMA_OBJECT *object)

说明

此函数获取对象句柄的对象信息。

参数

  • pima:指向 pima 类实例的指针。
  • pima_session:指向 PIMA 会话的指针
  • object_handle:对象的句柄
  • object:指向对象信息容器的指针

返回值

  • UX_SUCCESS:(0x00) 已完成数据传输。
  • UX_HOST_CLASS_PIMA_RC_SESSION_NOT_OPEN:(0x2003) 会话未打开
  • UX_MEMORY_INSUFFICIENT:(0x12) 内存不足,无法创建 PIMA 命令。

示例

/* We search for an object that is a picture or a script. */
object_index = 0;

while (object_index < pima_session -> ux_host_class_pima_session_nb_objects)
{
    /* Get the object info structure. */
    status = ux_**host_class_pima_object_info_get(pima, pima_session,
        pictbridge -> ux_pictbridge_object_handles_array[object_index], 
        pima_object);

    if (status != UX_SUCCESS)
    {
        /* Close the pima session. */
        status = ux_host_class_pima_session_close(pima, pima_session);

        return(UX_PICTBRIDGE_ERROR_INVALID_OBJECT_HANDLE );
    }
}

ux_host_class_pima_object_info_send

将对象信息发送到响应方。

原型

UINT ux_host_class_pima_object_info_send(
    UX_HOST_CLASS_PIMA *pima,
    UX_HOST_CLASS_PIMA_SESSION *pima_session,
    ULONG storage_id,
    ULONG parent_object_id,
    UX_HOST_CLASS_PIMA_OBJECT *object)

说明

此函数发送值为 storage_id 的存储容器的存储信息。 将对象发送到响应方前,发起方应使用此命令。

参数

  • pima:指向 pima 类实例的指针。
  • pima_session:指向 PIMA 会话的指针。
  • storage_id:目标存储 ID。
  • parent_object_id:应放置对象的响应方上的父 ObjectHandle。
  • object:指向对象信息容器的指针。

返回值

  • UX_SUCCESS:(0x00) 已完成数据传输。
  • UX_HOST_CLASS_PIMA_RC_SESSION_NOT_OPEN:(0x2003) 会话未打开
  • UX_MEMORY_INSUFFICIENT:(0x12) 内存不足,无法创建 PIMA 命令。

示例

/* Send a script info. */
status = ux_host_class_pima_object_info_send(pima, pima_session,
    0, 0, pima_object);

if (status != UX_SUCCESS)
{
    /* Close the pima session. */
    status = ux_host_class_pima_session_close(pima, pima_session);

    return(UX_ERROR);
}

ux_host_class_pima_object_open

打开存储在响应方中的对象。

原型

UINT ux_host_class_pima_object_open(
    UX_HOST_CLASS_PIMA *pima,
    UX_HOST_CLASS_PIMA_SESSION *pima_session,
    ULONG object_handle,
    UX_HOST_CLASS_PIMA_OBJECT *object)

说明

在读取或写入之前,此函数将在响应方上打开一个对象。

参数

  • pima:指向 pima 类实例的指针。
  • pima_session:指向 PIMA 会话的指针。
  • object_handle:对象的句柄。
  • object:指向对象信息容器的指针。

返回值

  • UX_SUCCESS:(0x00) 已完成数据传输。
  • UX_HOST_CLASS_PIMA_RC_SESSION_NOT_OPEN:(0x2003) 会话未打开
  • UX_HOST_CLASS_PIMA_RC_OBJECT_ALREADY_OPENED:(0x2021) 对象已打开。
  • UX_MEMORY_INSUFFICIENT:(0x12) 内存不足,无法创建 PIMA 命令。

示例

/* Open the object. */

status = ux_host_class_pima_object_open(pima, pima_session,
    object_handle, pima_object);

/* Check status. */
if (status != UX_SUCCESS)
    return(status);

ux_host_class_pima_object_get

获取存储在响应方中的对象。

原型

UINT ux_host_class_pima_object_get(
    UX_HOST_CLASS_PIMA *pima,
    UX_HOST_CLASS_PIMA_SESSION *pima_session,
    ULONG object_handle,
    UX_HOST_CLASS_PIMA_OBJECT *object,
    UCHAR *object_buffer,
    ULONG object_buffer_length,
    ULONG *object_actual_length)

说明

此函数获取响应方上的对象。

参数

  • pima:指向 pima 类实例的指针。
  • pima_session:指向 PIMA 会话的指针
  • object_handle:对象的句柄
  • object:指向对象信息容器的指针
  • object_buffer:对象数据的地址
  • object_buffer_length:请求的对象长度
  • object_actual_length:已返回的对象长度

返回值

  • UX_SUCCESS:(0x00) 已传输对象
  • UX_HOST_CLASS_PIMA_RC_SESSION_NOT_OPEN:(0x2003) 会话未打开
  • UX_HOST_CLASS_PIMA_RC_OBJECT_NOT_OPENED:(0x2023) 对象未打开。
  • UX_HOST_CLASS_PIMA_RC_ACCESS_DENIED:(0x200f) 拒绝访问对象
  • UX_HOST_CLASS_PIMA_RC_INCOMPLETE_TRANSFER:(0x2007) 传输未完成
  • UX_MEMORY_INSUFFICIENT:(0x12) 内存不足,无法创建 PIMA 命令。
  • UX_TRANSFER_ERROR:(0x23) 读取对象时出现传输错误

示例

/* Open the object. */

status = ux_host_class_pima_object_open(pima, pima_session,
    object_handle, pima_object);

/* Check status. */
if (status != UX_SUCCESS)
    return(status);

/* Set the object buffer pointer. */
object_buffer = pima_object ->ux_host_class_pima_object_buffer;

/* Obtain all the object data. */
while(object_length != 0)
{
    /* Calculate what length to request. */
    if (object_length > UX_PICTBRIDGE_MAX_PIMA_OBJECT_BUFFER)
        /* Request maximum length. */
        requested_length = UX_PICTBRIDGE_MAX_PIMA_OBJECT_BUFFER;
    else
        /* Request remaining length. */
        requested_length = object_length;

    /* Get the object data. */
    status = ux_host_class_pima_object_get(pima, pima_session,
        object_handle, pima_object, object_buffer,
        requested_length, &actual_length);

    if (status != UX_SUCCESS)
    {
        /* We had a problem, abort the transfer. */
        ux_host_class_pima_object_transfer_abort(pima, pima_session,
            object_handle, pima_object);

        /* And close the object. */
        ux_host_class_pima_object_close(pima, pima_session,
            object_handle, pima_object, object);

        return(status);

    }

    /* We have received some data, update the length remaining. */
    object_length -= actual_length;

    /* Update the buffer address. */
    object_buffer += actual_length;

}

/* Close the object. */
status = ux_host_class_pima_object_close(pima, pima_session,
    object_handle, pima_object, object);

ux_host_class_pima_object_send

发送存储在响应方中的对象。

原型

UINT ux_host_class_pima_object_send(
    UX_HOST_CLASS_PIMA *pima,
    UX_HOST_CLASS_PIMA_SESSION *pima_session,
    UX_HOST_CLASS_PIMA_OBJECT *object,
    UCHAR *object_buffer, ULONG object_buffer_length)

说明

此函数将对象发送到响应方。

参数

  • pima:指向 pima 类实例的指针。
  • pima_session:指向 PIMA 会话的指针
  • object_handle:对象的句柄
  • object:指向对象信息容器的指针
  • object_buffer:对象数据的地址
  • object_buffer_length:请求的对象长度

返回值

  • UX_SUCCESS:(0x00) 已完成数据传输。
  • UX_HOST_CLASS_PIMA_RC_SESSION_NOT_OPEN:(0x2003) 会话未打开
  • UX_HOST_CLASS_PIMA_RC_OBJECT_NOT_OPENED:(0x2023) 对象未打开。
  • UX_HOST_CLASS_PIMA_RC_ACCESS_DENIED:(0x200f) 拒绝访问对象
  • UX_HOST_CLASS_PIMA_RC_INCOMPLETE_TRANSFER:(0x2007) 传输未完成
  • UX_MEMORY_INSUFFICIENT:(0x12) 内存不足,无法创建 PIMA 命令。
  • UX_TRANSFER_ERROR:(0x23) 写入对象时出现传输错误

示例

/* Open the object. */
status = ux_host_class_pima_object_open(pima, pima_session,
    object_handle, pima_object);

/* Get the object length. */
object_length = pima_object ->ux_host_class_pima_object_compressed_size;

/* Recall the object buffer address. */
pima_object_buffer = pima_object ->ux_host_class_pima_object_buffer;

/* Send all the object data. */
while(object_length != 0)
{
    /* Calculate what length to request. */
    if (object_length > UX_PICTBRIDGE_MAX_PIMA_OBJECT_BUFFER)
        /* Request maximum length. */
        requested_length = UX_PICTBRIDGE_MAX_PIMA_OBJECT_BUFFER;
    else
        /* Request remaining length. */
        requested_length = object_length;

    /* Send the object data. */
    status = ux_host_class_pima_object_send(pima,
        pima_session, pima_object,
        pima_object_buffer, requested_length);

    if (status != UX_SUCCESS)
    {
        /* Abort the transfer. */
        ux_host_class_pima_object_transfer_abort(pima, pima_session,
            object_handle, pima_object);

        /* Return status. */
        return(status);
    }

    /* We have sent some data, update the length remaining. */
    object_length -= requested_length;
}

/* Close the object. */
status = ux_host_class_pima_object_close(pima, pima_session, object_handle,
    pima_object, object);

ux_host_class_pima_thumb_get

获取存储在响应方中的 Thumb 对象。

原型

UINT ux_host_class_pima_thumb_get(
    UX_HOST_CLASS_PIMA *pima,
    UX_HOST_CLASS_PIMA_SESSION *pima_session,
    ULONG object_handle,
    UX_HOST_CLASS_PIMA_OBJECT *object,
    UCHAR *thumb_buffer, ULONG thumb_buffer_length,
    ULONG *thumb_actual_length)

说明

此函数获取响应方上的 Thumb 对象。

参数

  • pima:指向 pima 类实例的指针。
  • pima_session:指向 PIMA 会话的指针。
  • object_handle:对象的句柄。
  • object:指向对象信息容器的指针。
  • thumb_buffer:Thumb 对象数据的地址。
  • thumb_buffer_length:请求的 Thumb 对象的长度。
  • thumb_actual_length:返回的 Thumb 对象的长度。

返回值

  • UX_SUCCESS:(0x00) 已完成数据传输。
  • UX_HOST_CLASS_PIMA_RC_SESSION_NOT_OPEN:(0x2003) 会话未打开。
  • UX_HOST_CLASS_PIMA_RC_OBJECT_NOT_OPENED:(0x2023) 对象未打开。
  • UX_HOST_CLASS_PIMA_RC_ACCESS_DENIED:(0x200f) 拒绝访问对象。
  • UX_HOST_CLASS_PIMA_RC_INCOMPLETE_TRANSFER:(0x2007) 传输未完成。
  • UX_MEMORY_INSUFFICIENT:(0x12) 内存不足,无法创建 PIMA 命令。
  • UX_TRANSFER_ERROR:(0x23) 读取对象时出现传输错误。

示例

/* Get the thumb object data. */

status = ux_host_class_pima_thumb_get(pima, pima_session,
    object_handle, pima_object, object_buffer,
    requested_length, &actual_length);

if (status != UX_SUCCESS)
{
    /* And close the object. */
    ux_host_class_pima_object_close(pima, pima_session, object_handle, pima_object, object);

    return(status);
}

ux_host_class_pima_object_delete

删除存储在响应方中的对象。

原型

UINT ux_host_class_pima_object_delete(
    UX_HOST_CLASS_PIMA *pima,
    UX_HOST_CLASS_PIMA_SESSION *pima_session,
    ULONG object_handle)

说明

此函数删除响应方上的对象

参数

  • pima:指向 pima 类实例的指针。
  • pima_session:指向 PIMA 会话的指针
  • object_handle:对象的句柄

返回值

  • UX_SUCCESS:(0x00) 已删除对象。
  • UX_HOST_CLASS_PIMA_RC_SESSION_NOT_OPEN:(0x2003) 会话未打开。
  • UX_HOST_CLASS_PIMA_RC_ACCESS_DENIED:(0x200f) 无法删除对象。
  • UX_MEMORY_INSUFFICIENT:(0x12) 内存不足,无法创建 PIMA 命令。

示例

/* Delete the object. */
status = ux_host_class_pima_object_delete(pima, pima_session, object_handle, pima_object);

/* Check status. */
if (status != UX_SUCCESS)
    return(status);

ux_host_class_pima_object_close

关闭存储在响应方中的对象

原型

UINT ux_host_class_pima_object_close(
    UX_HOST_CLASS_PIMA *pima,
    UX_HOST_CLASS_PIMA_SESSION *pima_session,
    ULONG object_handle, UX_HOST_CLASS_PIMA_OBJECT *object)

说明

此函数关闭响应方上的对象。

参数

  • pima:指向 pima 类实例的指针。
  • pima_session:指向 PIMA 会话的指针。
  • object_handle:对象的句柄。
  • object:指向对象的指针。

返回值

  • UX_SUCCESS:(0x00) 已关闭对象。
  • UX_HOST_CLASS_PIMA_RC_SESSION_NOT_OPEN:(0x2003) 会话未打开。
  • UX_HOST_CLASS_PIMA_RC_OBJECT_NOT_OPENED:(0x2023) 对象未打开。
  • UX_MEMORY_INSUFFICIENT:(0x12) 内存不足,无法创建 PIMA 命令。

示例

/* Close the object. */
status = ux_host_class_pima_object_close(pima, pima_session, object_handle, object);

ux_host_class_gser_read

从通用序列接口读取。

原型

UINT ux_host_class_gser_read(
    UX_HOST_CLASS_GSER *gser,
    ULONG interface_index,
    UCHAR *data_pointer,
    ULONG requested_length,
    ULONG *actual_length)

说明

此函数从通用序列接口读取。 调用阻塞,仅在出现错误或传输完成时返回。

参数

  • gser:指向 gser 类实例的指针。
  • interface_index:要从其中读取的接口索引。
  • data_pointer:指向数据有效负载的缓冲区地址的指针。
  • requested_length:要接收的长度。
  • actual_length:实际接收的长度。

返回值

  • UX_SUCCESS:(0x00) 已完成数据传输。
  • UX_TRANSFER_TIMEOUT:(0x5c) 传输超时,读取未完成。

示例

UINT status;

/* The following example illustrates this service. */
status = ux_host_class_gser_read(cdc_acm, interface_index,data_pointer, requested_length, &actual_length);

/* If status equals UX_SUCCESS, the operation was successful. */

ux_host_class_gser_write

写入通用序列接口。

原型

UINT ux_host_class_gser_write(
    UX_HOST_CLASS_GSER *gser,
    ULONG interface_index,
    UCHAR *data_pointer,
    ULONG requested_length,
    ULONG *actual_length)

说明

此函数写入通用序列接口。 调用阻塞,仅在出现错误或传输完成时返回。

参数

  • gser:指向 gser 类实例的指针。
  • interface_index:要写入的接口。
  • data_pointer:指向数据有效负载的缓冲区地址的指针。
  • requested_length:要发送的长度。
  • actual_length:实际发送的长度。

返回值

  • UX_SUCCESS:(0x00) 已完成数据传输。
  • UX_TRANSFER_TIMEOUT:(0x5c) 传输超时,写入未完成。

示例

UINT status;

/* The following example illustrates this service. */
status = ux_host_class_cdc_acm_write(gser, data_pointer, requested_length, &actual_length);

/* If status equals UX_SUCCESS, the operation was successful. */

ux_host_class_gser_ioctl

对通用序列接口执行 IOCTL 函数。

原型

UINT ux_host_class_gser_ioctl(
    UX_HOST_CLASS_GSER *gser,
    ULONG ioctl_function,
    VOID *parameter)

说明

此函数对 gser 接口执行特定的 ioctl 函数。 调用阻塞,仅在出现错误或命令完成时返回。

参数

  • gser:指向 gser 类实例的指针。
  • ioctl_function:要执行的 ioctl 函数。 查看以下表获取一个允许的 ioctl 函数。
  • parameter:指向特定于 ioctl 的参数的指针

返回值

  • UX_SUCCESS:(0x00) 已完成数据传输。
  • UX_MEMORY_INSUFFICIENT:(0x12) 内存不足。
  • UX_HOST_CLASS_UNKNOWN:(0x59) 错误的类实例
  • UX_FUNCTION_NOT_SUPPORTED:(0x54) 未知 IOCTL 函数。

IOCTL 函数

  • UX_HOST_CLASS_GSER_IOCTL_SET_LINE_CODING
  • UX_HOST_CLASS_GSER_IOCTL_GET_LINE_CODING
  • UX_HOST_CLASS_GSER_IOCTL_SET_LINE_STATE
  • UX_HOST_CLASS_GSER_IOCTL_SEND_BREAK
  • UX_HOST_CLASS_GSER_IOCTL_ABORT_IN_PIPE
  • UX_HOST_CLASS_GSER_IOCTL_ABORT_OUT_PIPE
  • UX_HOST_CLASS_GSER_IOCTL_NOTIFICATION_CALLBACK
  • UX_HOST_CLASS_GSER_IOCTL_GET_DEVICE_STATUS

示例

UINT status;

/* The following example illustrates this service. */

status = ux_host_class_gser_ioctl(gser,
    UX_HOST_CLASS_GSER_IOCTL_GET_LINE_CODING,
    (VOID *)&line_coding);

/* If status equals UX_SUCCESS, the operation was successful. */

ux_host_class_gser_reception_start

在通用序列接口上启动接收

原型

UINT ux_host_class_gser_reception_start(
    UX_HOST_CLASS_GSER *gser,
    UX_HOST_CLASS_GSER_RECEPTION *gser_reception)

说明

此函数在通用序列类接口上启动接收。 此函数允许非阻塞接收。 接收到缓冲区时,将在应用程序中调用回调。

参数

  • gser:指向 gser 类实例的指针。
  • gser_reception:包含接收参数的结构

返回值

  • UX_SUCCESS:(0x00) 已完成数据传输。
  • UX_HOST_CLASS_UNKNOWN:(0x59) 错误的类实例
  • UX_ERROR:(0x01) 错误

示例

/* Start the reception for gser. AT commands are on interface 2. */
gser_reception.ux_host_class_gser_reception_interface_index =
    UX_DEMO_GSER_AT_INTERFACE;
gser_reception.ux_host_class_gser_reception_block_size =
    UX_DEMO_RECEPTION_BLOCK_SIZE;
gser_reception.ux_host_class_gser_reception_data_buffer =
    gser_reception_buffer;
gser_reception.ux_host_class_gser_reception_data_buffer_size =
    UX_DEMO_RECEPTION_BUFFER_SIZE;
gser_reception.ux_host_class_gser_reception_callback =
    tx_demo_thread_callback;

ux_host_class_gser_reception_start(gser, &gser_reception);

ux_host_class_gser_reception_stop

在通用序列接口上停止接收

原型

UINT ux_host_class_gser_reception_stop(
    UX_HOST_CLASS_GSER *gser,
    UX_HOST_CLASS_GSER_RECEPTION *gser_reception)

说明

此函数在通用序列类接口上停止接收。

参数

  • gser:指向 gser 类实例的指针。
  • gser_reception:包含接收参数的结构

返回值

  • UX_SUCCESS:(0x00) 已完成数据传输。
  • UX_HOST_CLASS_UNKNOWN:(0x59) 错误的类实例
  • UX_ERROR:(0x01) 错误

示例

/* Stops the reception for gser. */
ux_host_class_gser_reception_stop(gser, &gser_reception);