1 /*
2  * Copyright (C) 2009 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #ifndef ANDROID_USB_API_ADB_HELPER_ROUTINES_H__
18 #define ANDROID_USB_API_ADB_HELPER_ROUTINES_H__
19 /** \file
20   This file consists of declarations of helper routines used
21   in the API.
22 */
23 
24 #include "adb_api_private_defines.h"
25 
26 /** \brief Converts access type and share mode from our enum into
27   SDK - complient values.
28 
29   @param[in] access_type Enumerated access type
30   @param[in] sharing_mode Enumerated share mode
31   @param[out] desired_access Will receive SDK - complient desired access
32          flags. This parameter can be NULL.
33   @param[out] desired_sharing Will receive SDK - complient share mode.
34          This parameter can be NULL.
35   @return True on success, false on failure, in which case GetLastError()
36           provides extended information about the error that occurred.
37 */
38 bool GetSDKComplientParam(AdbOpenAccessType access_type,
39                           AdbOpenSharingMode sharing_mode,
40                           ULONG* desired_access,
41                           ULONG* desired_sharing);
42 
43 /** \brief Given the hardware device information enumerates interfaces for
44   this device.
45 
46   @param[in] hardware_dev_info A handle to hardware device information obtained
47          from PnP manager via SetupDiGetClassDevs()
48   @param[in] class_id Device class ID how it is specified by our USB driver.
49   @param[in] exclude_removed If true interfaces with SPINT_REMOVED flag set
50          will be not included in the enumeration.
51   @param[in] active_only If true only active interfaces (with flag
52          SPINT_ACTIVE set) will be included in the enumeration.
53   @param[out] interfaces Upon successfull completion will consist of array of
54          all interfaces found for this device (matching all filters).
55   @return True on success, false on failure, in which case GetLastError()
56           provides extended information about the error that occurred.
57 */
58 bool EnumerateDeviceInterfaces(HDEVINFO hardware_dev_info,
59                                GUID class_id,
60                                bool exclude_removed,
61                                bool active_only,
62                                AdbEnumInterfaceArray* interfaces);
63 
64 /** \brief Enumerates all interfaces for our device class.
65 
66   This routine uses SetupDiGetClassDevs to get our device info and calls
67   EnumerateDeviceInterfaces to perform the enumeration.
68   @param[in] class_id Device class ID how it is specified by our USB driver
69   @param[in] flags Flags to pass to SetupDiGetClassDevs to filter devices. See
70          SetupDiGetClassDevs() in SDK for more info on these flags.
71   @param[in] exclude_removed If true interfaces with SPINT_REMOVED flag set
72          will be not included in the enumeration.
73   @param[in] active_only If true only active interfaces (with flag
74          SPINT_ACTIVE set) will be included in the enumeration.
75   @param[out] interfaces Upon successfull completion will consist of array of
76          all interfaces found for this device (matching all filters).
77   @return True on success, false on failure, in which case GetLastError()
78           provides extended information about the error that occurred.
79 */
80 bool EnumerateDeviceInterfaces(GUID class_id,
81                                ULONG flags,
82                                bool exclude_removed,
83                                bool active_only,
84                                AdbEnumInterfaceArray* interfaces);
85 
86 /** \brief Given the hardware device information and data gets data details.
87 
88   Given the hardware_dev_info, representing a handle to the plug and
89   play information, and dev_info_data, representing a specific usb device,
90   gets detailed data about the device (interface).
91   @param[in] hardware_dev_info A handle to hardware device information obtained
92          from PnP manager via SetupDiGetClassDevs()
93   @param[in] dev_info_data Device information data obtained via call to
94          SetupDiEnumDeviceInterfaces()
95   @param[out] dev_info_detail_data Upon successfull completion will consist of
96          the detailed data about device interface. This routine always
97          allocates memory for the output structure so content of this pointer
98          doesn't matter and will be overwritten by this routine. The caller
99          of this method is responsible for freeing allocated data using free()
100          routine.
101   @return True on success, false on failure, in which case GetLastError()
102           provides extended information about the error that occurred.
103 */
104 bool GetUsbDeviceDetails(HDEVINFO hardware_dev_info,
105                        PSP_DEVICE_INTERFACE_DATA dev_info_data,
106                        PSP_DEVICE_INTERFACE_DETAIL_DATA* dev_info_detail_data);
107 
108 /** \brief Given the hardware device information and data gets device name.
109 
110   Given the hardware_dev_info, representing a handle to the plug and
111   play information, and dev_info_data, representing a specific usb device,
112   gets device name. This routine uses GetUsbDeviceDetails to extract device
113   name.
114   @param[in] hardware_dev_info A handle to hardware device information obtained
115          from PnP manager via SetupDiGetClassDevs()
116   @param[in] dev_info_data Device information data obtained via call to
117          SetupDiEnumDeviceInterfaces()
118   @param[out] name Upon successfull completion will have name for the device.
119   @return True on success, false on failure, in which case GetLastError()
120           provides extended information about the error that occurred.
121 */
122 bool GetUsbDeviceName(HDEVINFO hardware_dev_info,
123                       PSP_DEVICE_INTERFACE_DATA dev_info_data,
124                       std::wstring* name);
125 
126 /** \brief Checks if given interface is available via custom USB driver.
127 
128   In this routine we will query the given interface with an IOCTL that should
129   be supported by the custom driver. If IOCTL fails, we make a conclusion that
130   this interface is available via WinUsb, and not via custom USB driver.
131   @param[in] interface_name Name of the interface to check.
132   @return true if interface is available via custom USB driver, or false
133           otherwise.
134 */
135 bool IsLegacyInterface(const wchar_t* interface_name);
136 
137 #endif  // ANDROID_USB_API_ADB_HELPER_ROUTINES_H__
138