functions.sgml

This libusb version 0.1.12. libusb is a library which allows userspace application access to USB de

          </funcprototype>
        </funcsynopsis>
        <para><function>usb_release_interface</function> releases an interface previously claimed with <xref linkend="function.usbclaiminterface">. The interface parameter is the value as specified in the descriptor field bInterfaceNumber. Returns 0 on success or &lt; 0 on error.</para>
      </refsect1>
    </refentry>
  </reference>

  <reference id="ref.control">
    <title>Control Transfers</title>
    <partintro>
      <para>This group of functions allow applications to send messages to the default control pipe.</para>
    </partintro>

    <refentry id="function.usbcontrolmsg">
      <refnamediv>
        <refname>usb_control_msg</refname>
        <refpurpose>Send a control message to a device</refpurpose>
      </refnamediv>
      <refsect1>
        <title>Description</title>
        <funcsynopsis>
          <funcprototype>
            <funcdef>int <function>usb_control_msg</function></funcdef>
            <paramdef>usb_dev_handle *<parameter>dev</parameter></paramdef>
            <paramdef>int <parameter>requesttype</parameter></paramdef>
            <paramdef>int <parameter>request</parameter></paramdef>
            <paramdef>int <parameter>value</parameter></paramdef>
            <paramdef>int <parameter>index</parameter></paramdef>
            <paramdef>char *<parameter>bytes</parameter></paramdef>
            <paramdef>int <parameter>size</parameter></paramdef>
            <paramdef>int <parameter>timeout</parameter></paramdef>
          </funcprototype>
        </funcsynopsis>
        <para><function>usb_control_msg</function> performs a control request to the default control pipe on a device. The parameters mirror the types of the same name in the USB specification. Returns number of bytes written/read or &lt; 0 on error.</para>
      </refsect1>
    </refentry>

    <refentry id="function.usbgetstring">
      <refnamediv>
        <refname>usb_get_string</refname>
        <refpurpose>Retrieves a string descriptor from a device</refpurpose>
      </refnamediv>
      <refsect1>
        <title>Description</title>
        <funcsynopsis>
          <funcprototype>
            <funcdef>int <function>usb_get_string</function></funcdef>
            <paramdef>usb_dev_handle *<parameter>dev</parameter></paramdef>
            <paramdef>int <parameter>index</parameter></paramdef>
            <paramdef>int <parameter>langid</parameter></paramdef>
            <paramdef>char *<parameter>buf</parameter></paramdef>
            <paramdef>size_t <parameter>buflen</parameter></paramdef>
          </funcprototype>
        </funcsynopsis>
        <para><function>usb_get_string</function> retrieves the string descriptor specified by index and langid from a device. The string will be returned in Unicode as specified by the USB specification. Returns the number of bytes returned in <varname>buf</varname> or &lt; 0 on error.</para>
      </refsect1>
    </refentry>

    <refentry id="function.usbgetstringsimple">
      <refnamediv>
        <refname>usb_get_string_simple</refname>
        <refpurpose>Retrieves a string descriptor from a device using the first language</refpurpose>
      </refnamediv>
      <refsect1>
        <title>Description</title>
        <funcsynopsis>
          <funcprototype>
            <funcdef>int <function>usb_get_string_simple</function></funcdef>
            <paramdef>usb_dev_handle *<parameter>dev</parameter></paramdef>
            <paramdef>int <parameter>index</parameter></paramdef>
            <paramdef>char *<parameter>buf</parameter></paramdef>
            <paramdef>size_t <parameter>buflen</parameter></paramdef>
          </funcprototype>
        </funcsynopsis>
        <para><function>usb_get_string_simple</function> is a wrapper around <function>usb_get_string</function> that retrieves the string description specified by index in the first language for the descriptor and converts it into C style ASCII. Returns number of bytes returned in <varname>buf</varname> or &lt; 0 on error.</para>
      </refsect1>
    </refentry>

    <refentry id="function.usbgetdescriptor">
      <refnamediv>
        <refname>usb_get_descriptor</refname>
        <refpurpose>Retrieves a descriptor from a device's default control pipe</refpurpose>
      </refnamediv>
      <refsect1>
        <title>Description</title>
        <funcsynopsis>
          <funcprototype>
            <funcdef>int <function>usb_get_descriptor</function></funcdef>
            <paramdef>usb_dev_handle *<parameter>dev</parameter></paramdef>
            <paramdef>unsigned char <parameter>type</parameter></paramdef>
            <paramdef>unsigned char <parameter>index</parameter></paramdef>
            <paramdef>void *<parameter>buf</parameter></paramdef>
            <paramdef>int <parameter>size</parameter></paramdef>
          </funcprototype>
        </funcsynopsis>
        <para><function>usb_get_descriptor</function> retrieves a descriptor from the device identified by the <varname>type</varname> and <varname>index</varname> of the descriptor from the default control pipe. Returns number of bytes read for the descriptor or &lt; 0 on error.</para>
        <para>See <xref linkend="function.usbgetdescriptorbyendpoint"> for a function that allows the control endpoint to be specified.</para>
      </refsect1>
    </refentry>

    <refentry id="function.usbgetdescriptorbyendpoint">
      <refnamediv>
        <refname>usb_get_descriptor_by_endpoint</refname>
        <refpurpose>Retrieves a descriptor from a device</refpurpose>
      </refnamediv>
      <refsect1>
        <title>Description</title>
        <funcsynopsis>
          <funcprototype>
            <funcdef>int <function>usb_get_descriptor_by_endpoint</function></funcdef>
            <paramdef>usb_dev_handle *<parameter>dev</parameter></paramdef>
            <paramdef>int <parameter>ep</parameter></paramdef>
            <paramdef>unsigned char <parameter>type</parameter></paramdef>
            <paramdef>unsigned char <parameter>index</parameter></paramdef>
            <paramdef>void *<parameter>buf</parameter></paramdef>
            <paramdef>int <parameter>size</parameter></paramdef>
          </funcprototype>
        </funcsynopsis>
        <para><function>usb_get_descriptor_by_endpoint</function> retrieves a descriptor from the device identified by the <varname>type</varname> and <varname>index</varname> of the descriptor from the control pipe identified by <varname>ep</varname>. Returns number of bytes read for the descriptor or &lt; 0 on error.</para>
      </refsect1>
    </refentry>
  </reference>

  <reference id="ref.bulk">
    <title>Bulk Transfers</title>
    <partintro>
      <para>This group of functions allow applications to send and receive data via bulk pipes.</para>
    </partintro>

    <refentry id="function.usbbulkwrite">
      <refnamediv>
        <refname>usb_bulk_write</refname>
        <refpurpose>Write data to a bulk endpoint</refpurpose>
      </refnamediv>
      <refsect1>
        <title>Description</title>
        <funcsynopsis>
          <funcprototype>
            <funcdef>int <function>usb_bulk_write</function></funcdef>
            <paramdef>usb_dev_handle *<parameter>dev</parameter></paramdef>
            <paramdef>int <parameter>ep</parameter></paramdef>
            <paramdef>char *<parameter>bytes</parameter></paramdef>
            <paramdef>int <parameter>size</parameter></paramdef>
            <paramdef>int <parameter>timeout</parameter></paramdef>
          </funcprototype>
        </funcsynopsis>
        <para><function>usb_bulk_write</function> performs a bulk write request to the endpoint specified by <varname>ep</varname>. Returns number of bytes written on success or &lt; 0 on error.</para>
      </refsect1>
    </refentry>

    <refentry id="function.usbbulkread">
      <refnamediv>
        <refname>usb_bulk_read</refname>
        <refpurpose>Read data from a bulk endpoint</refpurpose>
      </refnamediv>
      <refsect1>
        <title>Description</title>
        <funcsynopsis>
          <funcprototype>
            <funcdef>int <function>usb_bulk_read</function></funcdef>
            <paramdef>usb_dev_handle *<parameter>dev</parameter></paramdef>
            <paramdef>int <parameter>ep</parameter></paramdef>
            <paramdef>char *<parameter>bytes</parameter></paramdef>
            <paramdef>int <parameter>size</parameter></paramdef>
            <paramdef>int <parameter>timeout</parameter></paramdef>
          </funcprototype>
        </funcsynopsis>
        <para><function>usb_bulk_read</function> performs a bulk read request to the endpoint specified by <varname>ep</varname>. Returns number of bytes read on success or &lt; 0 on error.</para>
      </refsect1>
    </refentry>
  </reference>

  <reference id="ref.interrupt">
    <title>Interrupt Transfers</title>
    <partintro>
      <para>This group of functions allow applications to send and receive data via interrupt pipes.</para>
    </partintro>

    <refentry id="function.usbinterruptwrite">
      <refnamediv>
        <refname>usb_interrupt_write</refname>
        <refpurpose>Write data to an interrupt endpoint</refpurpose>
      </refnamediv>
      <refsect1>
        <title>Description</title>
        <funcsynopsis>
          <funcprototype>
            <funcdef>int <function>usb_interrupt_write</function></funcdef>
            <paramdef>usb_dev_handle *<parameter>dev</parameter></paramdef>
            <paramdef>int <parameter>ep</parameter></paramdef>
            <paramdef>char *<parameter>bytes</parameter></paramdef>
            <paramdef>int <parameter>size</parameter></paramdef>
            <paramdef>int <parameter>timeout</parameter></paramdef>
          </funcprototype>
        </funcsynopsis>
        <para><function>usb_interrupt_write</function> performs an interrupt write request to the endpoint specified by <varname>ep</varname>. Returns number of bytes written on success or &lt; 0 on error.</para>
      </refsect1>
    </refentry>

    <refentry id="function.usbinterruptread">
      <refnamediv>
        <refname>usb_interrupt_read</refname>
        <refpurpose>Read data from a interrupt endpoint</refpurpose>
      </refnamediv>
      <refsect1>
        <title>Description</title>
        <funcsynopsis>
          <funcprototype>
            <funcdef>int <function>usb_interrupt_read</function></funcdef>
            <paramdef>usb_dev_handle *<parameter>dev</parameter></paramdef>
            <paramdef>int <parameter>ep</parameter></paramdef>
            <paramdef>char *<parameter>bytes</parameter></paramdef>
            <paramdef>int <parameter>size</parameter></paramdef>
            <paramdef>int <parameter>timeout</parameter></paramdef>
          </funcprototype>
        </funcsynopsis>
        <para><function>usb_interrupt_read</function> performs a interrupt read request to the endpoint specified by <varname>ep</varname>. Returns number of bytes read on success or &lt; 0 on error.</para>
      </refsect1>
    </refentry>
  </reference>

  <reference id="ref.nonportable">
    <title>Non Portable</title>
    <partintro>
      <para>These functions are non portable. They may expose some part of the USB API on one OS or perhaps a couple, but not all. They are all marked with the string _np at the end of the function name.</para>
      <para>A C preprocessor macro will be defined if the function is implemented. The form is LIBUSB_HAS_ prepended to the function name, without the leading "usb_", in all caps. For example, if usb_get_driver_np is implemented, LIBUSB_HAS_GET_DRIVER_NP will be defined.</para>
    </partintro>

    <refentry id="function.usbgetdrivernp">
      <refnamediv>
        <refname>usb_get_driver_np</refname>
        <refpurpose>Get driver name bound to interface</refpurpose>
      </refnamediv>
      <refsect1>
        <title>Description</title>
        <funcsynopsis>
          <funcprototype>
            <funcdef>int <function>usb_get_driver_np</function></funcdef>
            <paramdef>usb_dev_handle *<parameter>dev</parameter></paramdef>
            <paramdef>int <parameter>interface</parameter></paramdef>
            <paramdef>char *<parameter>name</parameter></paramdef>
            <paramdef>int <parameter>namelen</parameter></paramdef>
          </funcprototype>
        </funcsynopsis>
        <para>This function will obtain the name of the driver bound to the interface specified by the parameter <parameter>interface</parameter> and place it into the buffer named <parameter>name</parameter> limited to <parameter>namelen</parameter> characters. Returns 0 on success or &lt; 0 on error.</para>
        <para>Implemented on Linux only.</para>
      </refsect1>
    </refentry>

    <refentry id="function.usbdetachkerneldrivernp">
      <refnamediv>
        <refname>usb_detach_kernel_driver_np</refname>
        <refpurpose>Detach kernel driver from interface</refpurpose>
      </refnamediv>
      <refsect1>
        <title>Description</title>
        <funcsynopsis>
          <funcprototype>
            <funcdef>int <function>usb_detach_kernel_driver_np</function></funcdef>
            <paramdef>usb_dev_handle *<parameter>dev</parameter></paramdef>
            <paramdef>int <parameter>interface</parameter></paramdef>
          </funcprototype>
        </funcsynopsis>
        <para>This function will detach a kernel driver from the interface specified by parameter <parameter>interface</parameter>. Applications using libusb can then try claiming the interface. Returns 0 on success or &lt; 0 on error.</para>
        <para>Implemented on Linux only.</para>
      </refsect1>
    </refentry>
  </reference>