summaryrefslogtreecommitdiff
path: root/usbredirhost/usbredirhost.h
blob: 87bcf54888628e6d009b15432bdd421a61dc8e49 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
/* usbredirhost.c usb network redirection usb host code header

   Copyright 2010-2011 Red Hat, Inc.

   Red Hat Authors:
   Hans de Goede <hdegoede@redhat.com>

   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Lesser General Public
   License as published by the Free Software Foundation; either
   version 2.1 of the License, or (at your option) any later version.

   This library is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Lesser General Public License for more details.

   You should have received a copy of the GNU Lesser General Public
   License along with this library; if not, see <http://www.gnu.org/licenses/>.
*/
#ifndef __USBREDIRHOST_H
#define __USBREDIRHOST_H

#include <libusb.h>
#include "usbredirparser.h"
#include "usbredirfilter.h"

struct usbredirhost;

typedef void (*usbredirhost_flush_writes)(void *priv);

/* This function *takes ownership of* the passed in libusb_device_handle
   and sends the initial usb_redir_hello packet to the usb-guest.

   log_func is called by the usbredirhost to log various messages

   read_guest_data_func / write_guest_data_func are called by the
   usbredirhost to read/write data from/to the usb-guest.

   This function returns a pointer to the created usbredirhost object on
   success, or NULL on failure. Note that the passed in libusb_device_handle
   is closed on failure.

   Note:
   1) Both the usbredirtransport_log and the usbredirtransport_write
      callbacks may get called before this function completes.
   2) It is the responsibility of the code instantiating the usbredirhost
      to make sure that libusb_handle_events gets called (using the
      libusb_context from the passed in libusb_device_handle) when there are
      events waiting on the filedescriptors libusb_get_pollfds returns
   3) usbredirhost is partially multi-thread safe, see README.multi-thread
*/

enum {
    usbredirhost_fl_write_cb_owns_buffer = 0x01, /* See usbredirparser.h */
};

struct usbredirhost *usbredirhost_open(
    libusb_context *usb_ctx,
    libusb_device_handle *usb_dev_handle,
    usbredirparser_log log_func,
    usbredirparser_read  read_guest_data_func,
    usbredirparser_write write_guest_data_func,
    void *func_priv, const char *version, int verbose, int flags);

/* See README.multi-thread */
struct usbredirhost *usbredirhost_open_full(
    libusb_context *usb_ctx,
    libusb_device_handle *usb_dev_handle,
    usbredirparser_log log_func,
    usbredirparser_read  read_guest_data_func,
    usbredirparser_write write_guest_data_func,
    usbredirhost_flush_writes flush_writes_func,
    usbredirparser_alloc_lock alloc_lock_func,
    usbredirparser_lock lock_func,
    usbredirparser_unlock unlock_func,
    usbredirparser_free_lock free_lock_func,
    void *func_priv, const char *version, int verbose, int flags);

/* Close the usbredirhost, returning control of the device back to any
   host kernel drivers for it, freeing any allocated memory, etc.

   Note this function calls libusb_handle_events to "reap" cancelled
   urbs before closing the libusb device handle. This means that if you
   are using the same libusb context for other purposes your transfer complete
   callbacks may get called! */
void usbredirhost_close(struct usbredirhost *host);

/* Call this whenever there is data ready for the usbredirhost to read from
   the usb-guest
   returns 0 on success, or an error code from the below enum on error.
   On an usbredirhost_read_io_error this function will continue where it
   left of the last time on the next call. On an usbredirhost_read_parse_error
   it will skip to the next packet (*). On an usbredirhost_read_device_rejected
   error, you are expected to call usbredirhost_close().
   *) As determined by the faulty's package headers length field */
enum {
    usbredirhost_read_io_error        = -1,
    usbredirhost_read_parse_error     = -2,
    usbredirhost_read_device_rejected = -3,
};
int usbredirhost_read_guest_data(struct usbredirhost *host);

/* If this returns true there is data queued to write to the usb-guest */
int usbredirhost_has_data_to_write(struct usbredirhost *host);

/* Call this when usbredirhost_has_data_to_write returns true
   returns 0 on success, -1 if a write error happened.
   If a write error happened, this function will retry writing any queued data
   on the next call, and will continue doing so until it has succeeded! */
enum {
    usbredirhost_write_io_error       = -1,
};
int usbredirhost_write_guest_data(struct usbredirhost *host);

/* When passing the usbredirhost_fl_write_cb_owns_buffer flag to
   usbredirhost_open, this function must be called to free the data buffer
   passed to write_guest_data_func when done with this buffer. */
void usbredirhost_free_write_buffer(struct usbredirhost *host, uint8_t *data);

/* Get the *usbredir-guest's* filter, if any. If there is no filter,
   rules is set to NULL and rules_count to 0. */
void usbredirhost_get_guest_filter(struct usbredirhost *host,
    struct usbredirfilter_rule **rules_ret, int *rules_count_ret);

/* Get device and config descriptors from the USB device dev, and call
   usbredirfilter_check with the passed in filter rules and the needed info
   from the descriptors, flags gets passed to usbredirfilter_check unmodified.
   See the documentation of usbredirfilter_check for more details.

   Return value: -EIO or -ENOMEM when getting the descriptors fails, otherwise
       it returns the return value of the usbredirfilter_check call. */
int usbredirhost_check_device_filter(struct usbredirfilter_rule *rules,
    int rules_count, libusb_device *dev, int flags);

#endif