adb_helper_routines.h revision 52d4c30ca52320ec92d1d1ddc8db3f07f69c4f98 
1/*
2 * Copyright (C) 2006 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 access_type[in] Enumerated access type
30  @param sharing_mode[in] Enumerated share mode
31  @param desired_access[out] Will receive SDK - complient desired access
32         flags. This parameter can be NULL.
33  @param desired_sharing[out] 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*/
38bool GetSDKComplientParam(AdbOpenAccessType access_type,
39                          AdbOpenSharingMode sharing_mode,
40                          ULONG* desired_access,
41                          ULONG* desired_sharing);
42
43/** \brief
44  Given the hardware device information enumerates interfaces for this device
45
46  @param hardware_dev_info[in] A handle to hardware device information obtained
47         from PnP manager via SetupDiGetClassDevs()
48  @param class_id[in] Device class ID how it is specified by our USB driver
49  @param exclude_removed[in] If true interfaces with SPINT_REMOVED flag set
50         will be not included in the enumeration.
51  @param active_only[in] If 'true' only active interfaces (with flag
52         SPINT_ACTIVE set) will be included in the enumeration.
53  @param interfaces[out] 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*/
58bool 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 class_id[in] Device class ID how it is specified by our USB driver
69  @param flags[in] Flags to pass to SetupDiGetClassDevs to filter devices. See
70         SetupDiGetClassDevs() in SDK for more info on these flags.
71  @param exclude_removed[in] If true interfaces with SPINT_REMOVED flag set
72         will be not included in the enumeration.
73  @param active_only[in] If 'true' only active interfaces (with flag
74         SPINT_ACTIVE set) will be included in the enumeration.
75  @param interfaces[out] 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*/
80bool 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 hardware_dev_info[in] A handle to hardware device information obtained
92         from PnP manager via SetupDiGetClassDevs()
93  @param dev_info_data[in] Device information data obtained via call to
94         SetupDiEnumDeviceInterfaces()
95  @param dev_info_detail_data[out] 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*/
104bool 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 hardware_dev_info[in] A handle to hardware device information obtained
115         from PnP manager via SetupDiGetClassDevs()
116  @param dev_info_data[in] Device information data obtained via call to
117         SetupDiEnumDeviceInterfaces()
118  @param name[out] 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*/
122bool GetUsbDeviceName(HDEVINFO hardware_dev_info,
123                      PSP_DEVICE_INTERFACE_DATA dev_info_data,
124                      std::wstring* name);
125
126#endif  // ANDROID_USB_API_ADB_HELPER_ROUTINES_H__
127