Changes between Version 49 and Version 50 of libwdi/usage


Ignore:
Timestamp:
04/19/11 12:00:23 (2 years ago)
Author:
pbatard
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • libwdi/usage

    v49 v50  
    1 [http://libusb.org/wiki/libwdi/install (Previous)] [http://libusb.org/wiki/libwdi/signed_driver_walkthrough (Next)]  [http://libusb.org/wiki/libwdi#Documentation (Back to Table of Content)] 
    2  
    3 = API documentation & usage = 
    4 [[PageOutline(2-5, libwdi API)]] 
    5  
    6 This section documents the use of the libwdi API.[[BR]] 
    7  
    8 == Basic usage == 
    9  
    10 For those in a hurry, below is a basic example in C of how one would use libwdi to automatically install a driver, for all driverless USB devices present on a system. 
    11 {{{#!c 
    12 struct wdi_device_info *device, *list; 
    13  
    14 if (wdi_create_list(&list, NULL) == WDI_SUCCESS) { 
    15     for (device = list; device != NULL; device = device->next) { 
    16         printf("Installing driver for USB device: "%s" (%04X:%04X) 
    17 ", 
    18             device->desc, device->vid, device->pid); 
    19         if (wdi_prepare_driver(device, DEFAULT_DIR, INF_NAME, NULL) == WDI_SUCCESS) { 
    20             wdi_install_driver(device, DEFAULT_DIR, INF_NAME, NULL); 
    21         } 
    22     } 
    23     wdi_destroy_list(list); 
    24 } 
    25 }}} 
    26  
    27 In the program excerpt above, first we start by creating a list of all the driverless USB devices on the system using '''wdi_create_list'''. If any are found, the call returns success with a chained list of '''wdi_device_info''' elements containing, among other things, the system description of each device, as well as its USB VID & PID.[[BR]] 
    28 Using these properties, we then extract the driver files and generate an inf through '''wdi_prepare_driver''', and finally call '''wdi_install_driver''', which starts the Operating System driver installation procedure. 
    29  
    30 == Error Codes == 
    31  
    32 All of the liwdi API function, apart from '''wdi_strerror''', '''wdi_is_driver_supported''' and '''wdi_is_file_embedded''', return one of the error codes below.[[BR]] 
    33 The '''wdi_strerror''' function, documented in the next paragraph, is used to convert an error code to a human readable string.[[BR]] 
    34 Success is always indicated by a return value zero (WDI_SUCCESS) while any error will be a negative value.[[BR]] 
    35  
    36  * '''WDI_SUCCESS''':[[BR]] This code is used to indicate that the function completed successfully. Its value is hardcoded to 0. 
    37  
    38  * '''WDI_ERROR_IO''':[[BR]] This code indicates that the function call was unable to read or write the data it needs to perform a successful operation. 
    39  
    40  * '''WDI_ERROR_INVALID_PARAM''':[[BR]] This code is returned when one of the parameters provided by the user is not valid within the scope of the function usage. 
    41  
    42  * '''WDI_ERROR_ACCESS''':[[BR]] This code indicates that the system explicitly refused access to a resource needed to perform a successful operation. 
    43  
    44  * '''WDI_ERROR_NO_DEVICE''':[[BR]] This code is returned when either the user is trying to access a USB device that is unavailable, or when a request to enumerate a set of devices finds that none are available. 
    45  
    46  * '''WDI_ERROR_NOT_FOUND''':[[BR]] This code is returned when a non device element, required for the function to perform a successful operation, is unavailable. 
    47  
    48  * '''WDI_ERROR_BUSY''':[[BR]] This code is returned when a resource (device, I/O channel, etc) or a function that does not support concurrent is already in use. 
    49  
    50  * '''WDI_ERROR_TIMEOUT''':[[BR]] This code reports that an operation that has a time limit expired before it could be completed. 
    51  
    52  * '''WDI_ERROR_OVERFLOW''':[[BR]] This code indicates that an operation or API call returned more data than was requested. 
    53  
    54  * '''WDI_ERROR_PENDING_INSTALLATION''':[[BR]] This code indicates that the system is waiting for a previous driver installation operation to complete. 
    55  
    56  * '''WDI_ERROR_INTERRUPTED''':[[BR]] This code indicates that a system call was interrupted by another process. 
    57  
    58  * '''WDI_ERROR_RESOURCE''':[[BR]] This code indicates that a system resource required for the function to perform a successful operation, could not be allocated. This can occur if the system is running low on memory or disk, etc. 
    59  
    60  * '''WDI_ERROR_NOT_SUPPORTED''':[[BR]] This code indicates that the user requested an operation, or combination of operations, that the system does not currently support. 
    61  
    62  * '''WDI_ERROR_EXISTS''':[[BR]] This code is returned when an operation tried to create an entity (device, resource, etc.) that already exists and can only be unique. 
    63  
    64  * '''WDI_ERROR_USER_CANCEL''':[[BR]] This code indicates that the end user explicitly cancelled an operation, either when prompted or by forcefully interrupting an operation. 
    65  
    66  * '''WDI_ERROR_NEEDS_ADMIN''':[[BR]] This code is returned when a process does not have sufficient privileges to perform the administrative operations it requires. 
    67  
    68  * '''WDI_ERROR_WOW64''':[[BR]] This code is returned when a 32 bit process or operation is being run on in an incompatible 64 bit environment. 
    69  
    70  * '''WDI_ERROR_INF_SYNTAX''':[[BR]] This code is returned when the driver installation detects either a corrupted or improper inf file. 
    71  
    72  * '''WDI_ERROR_CAT_MISSING''':[[BR]] This code indicates that the driver installation required the presence of a cat file to match the inf, and could not find it. 
    73  
    74  * '''WDI_ERROR_UNSIGNED''':[[BR]] This code is returned when the system policy prevents the installation of unsigned drivers. 
    75  
    76  * '''WDI_ERROR_OTHER''':[[BR]] This code is returned for any error that does not fit in the categories above. 
    77  
    78 == Structures == 
    79  
    80 |---------------- 
    81 {{{#!td style="background: #eef" 
    82   '''struct [=#wdi_device_info wdi_device_info]''' 
    83 }}} 
    84 |---------------- 
    85 {{{#!td 
    86   This structure provides all the information related to the device installation 
    87   * '''struct wdi_device_info* next''' ''(Optional)''[[BR]]Used for wdi_device_info chained lists returned by '''wdi_create_list'''. If unused, set to NULL. 
    88   * '''unsigned short vid''' ''(Mandatory)''[[BR]]USB Vendor ID of the USB device. 
    89   * '''unsigned short pid''' ''(Mandatory)''[[BR]]USB Product ID of the USB device. 
    90   * '''bool is_composite''' ''(Mandatory)''[[BR]]Whether the device is a composite USB device.  
    91   * '''unsigned char mi''' ''(Optional)''[[BR]]Interface number for composite devices. If unused, set to 0. 
    92   * '''char* desc''' ''(Mandatory)''[[BR]]USB Device description string. UTF-8. 
    93   * '''char* driver''' ''(Optional)''[[BR]]Current driver (service) used by the device. If unused, set to NULL. 
    94   * '''char* device_id''' ''(Optional)''[[BR]]Microsoft's device URI string. If unused, set to NULL. 
    95   * '''char* hardware_id''' ''(Optional)''[[BR]]Microsoft's hardware ID string. If unused, set to NULL. 
    96 }}} 
    97 |---------------- 
    98 [[BR]] 
    99  
    100 |---------------- 
    101 {{{#!td style="background: #eef" 
    102   '''struct [=#wdi_options_create_list wdi_options_create_list]''' 
    103 }}} 
    104 |---------------- 
    105 {{{#!td 
    106   This structure is used by ''wdi_create_list'' to set optional parameters 
    107   * '''bool list_all''' [[BR]]indicates whether the list should enumerate all USB devices (true) or only USB devices that don't have a driver installed (false). If the pointer passed to the call is NULL, the default only list driverless devices (false). 
    108   * '''bool list_hubs''' [[BR]]when list_all is enabled, indicates whether the list should also include USB Hubs and Composite Parent devices (true) or not (false). If the pointer passed to the call is NULL, the default is not to list such devices (false). 
    109   * '''bool trim_whitespaces''' '[[BR]]indicates whether device description string retrieved during enumeration should be trimmed of trailing whitespaces. If the pointer passed to the call is NULL, the default is to not trim trailing whitespaces (false). 
    110 }}} 
    111 |---------------- 
    112 [[BR]] 
    113  
    114 |---------------- 
    115 {{{#!td style="background: #eef" 
    116   '''struct [=#wdi_options_prepare_driver wdi_options_prepare_driver]''' 
    117 }}} 
    118 |---------------- 
    119 {{{#!td 
    120   This structure is used by ''wdi_prepare_driver'' to set optional parameters 
    121   * '''int driver_type''' [[BR]]type of driver to extract. Should be either '''WDI_WINUSB''', '''WDI_LIBUSB''' or '''WDI_USER''', depending on whether WinUSB, libusb0.sys or a custom user driver should be used. [[BR]]If the pointer passed to the call is NULL, the default will be to use the first driver available, in the order above. 
    122   * '''char* vendor_name''' [[BR]]an UTF-8 string that will override the Vendor name generated for the inf. Ultimately, this content appears under "Manufacturer" in the device manager's device properties. [[BR]]If either the pointer passed to the call or this string is NULL, libwdi will try to resolve the vendor name from the device's vid by calling '''[#wdi_get_vendor_name wdi_get_vendor_name]'''[[BR]]If this option is provided, it takes precedence over automated resolution. 
    123 }}} 
    124 |---------------- 
    125 [[BR]] 
    126  
    127 |---------------- 
    128 {{{#!td style="background: #eef" 
    129   '''struct [=#wdi_options_install_driver wdi_options_install_driver]''' 
    130 }}} 
    131 |---------------- 
    132 {{{#!td 
    133   This structure is used by ''wdi_install_driver'' to set optional parameters. 
    134   * '''HWND hWnd''' [[BR]]Handle to a Window application that should receive a modal progress dialog. When this parameter is provided, a modal progress dialog will be displayed for the duration of the driver installation process. 
    135 }}} 
    136 |---------------- 
    137 [[BR]] 
    138  
    139 |---------------- 
    140 {{{#!td style="background: #eef" 
    141   '''struct [=#wdi_options_install_cert wdi_options_install_cert]''' 
    142 }}} 
    143 |---------------- 
    144 {{{#!td 
    145   This structure is used by ''wdi_install_trusted_certificate'' to set optional parameters. 
    146   * '''HWND hWnd''' [[BR]]Handle to a Window application that can receive a modal warning dialog. When this parameter is provided, a modal warning dialog may be displayed to let the user know that a certificate in the system's Trusted Publishers store is going to be added/updated. Note that this warning may also displayed in this parameter is NULL (this option is intended for re-centering of the warning with regards to the parent Windows application) 
    147   * '''bool disable_warning''' [[BR]]disables the above warning when set to true. For security reasons, disabling of the warning should only be set for distribution of a lwdi installer by the administrators of a corporate environment, as it will otherwise lead to a code signing certificate being installed as trusted without the end-user's knowledge, which is bad practice. 
    148 }}} 
    149 |---------------- 
    150  
    151 == Function Calls == 
    152  
    153 |---------------- 
    154 {{{#!td style="background: #eef" 
    155   '''const char* [=#wdi_strerror wdi_strerror](int errcode)'''  
    156 }}} 
    157 |---------------- 
    158 {{{#!td 
    159   '''Synopsis:''' 
    160     Convert a wdi error code to a human readable string. This can be used to provide a more explicit libwdi error message to the end users of your program. 
    161  
    162   '''Parameters:''' 
    163     '''errcode''': The '''enum wdi_error''' value to convert to an error message. 
    164  
    165   '''Return value:''' 
    166     The error message string (UTF-8). 
    167 }}} 
    168 |---------------- 
    169 [[BR]] 
    170  
    171 |---------------- 
    172 {{{#!td style="background: #eef" 
    173   '''const char* [=#wdi_get_vendor_name wdi_get_vendor_name](unsigned short vid)'''  
    174 }}} 
    175 |---------------- 
    176 {{{#!td 
    177   '''Synopsis:''' 
    178     Convert a Vendor ID value to a vendor name string. This can be used to resolve the manufacturer of a specific device in your program. 
    179  
    180   '''Parameters:''' 
    181     '''vid''': The Vendor ID to convert. 
    182  
    183   '''Return value:''' 
    184     The Vendor ID string (UTF-8) or NULL if the VID does not match any known Vendor ID. 
    185  
    186   '''Remarks:''' 
    187     The Vendor ID strings are based on the data maintained by Stephen J. Gowdy at [http://www.linux-usb.org/usb.ids]. 
    188 }}} 
    189 |---------------- 
    190 [[BR]] 
    191  
    192 |---------------- 
    193 {{{#!td style="background: #eef" 
    194   '''bool [=#wdi_is_driver_supported wdi_is_driver_supported](int driver_type, VS_FIXEDFILEINFO* driver_info)'''  
    195 }}} 
    196 |---------------- 
    197 {{{#!td 
    198   '''Synopsis:''' 
    199     Indicates if the selected driver is supported for the current the target platform. This is useful to:[[BR]]1. find out if the libwdi library being used embeds a specific driver[[BR]]2. check at runtime whether the above driver can be used on the current platform (eg. even if available, WinUSB is not compatible with Windows 2000 or Windows 2003, therefore the call would return false there) 
    200  
    201   '''Parameters:''' 
    202     '''driver_type''': either '''WDI_WINUSB''', '''WDI_LIBUSB''' or '''WDI_USER''', depending on whether the driver files to be checked are WinUSB, libusb0.sys or a custom user driver.[[BR]] 
    203     '''driver_info''': the address of a [http://msdn.microsoft.com/en-us/library/ms646997.aspx VS_FIXEDFILEINFO structure]. If this parameter is not NULL, and the driver is either WDI_WINUSB or WDI_LIBUSB, then a [http://msdn.microsoft.com/en-us/library/ms646997.aspx VS_FIXEDFILEINFO structure] will be filled. If driver information cannot be returned, then this structure is filled with zeroes. This can be used to retrieve the date and version of the driver file.  
    204   '''Return value:''' 
    205     A boolean indicating whether the driver is supported for installation. 
    206  
    207   '''Remarks:''' 
    208     The '''bool''' type is defined in libwdi.h. 
    209 }}} 
    210 |---------------- 
    211 [[BR]] 
    212  
    213 |---------------- 
    214 {{{#!td style="background: #eef" 
    215   '''bool [=#wdi_is_file_embedded wdi_is_file_embedded](char* path, char* name)'''  
    216 }}} 
    217 |---------------- 
    218 {{{#!td 
    219   '''Synopsis:''' 
    220     Indicates if the file identified by (path, name) or just (name) is available from the library binary. This can be useful for instance if you are planning to install a driver signing certificate, and want to confirm that the .cer file has properly been embedded in the archive, before calling wdi_install_trusted_certificate. 
    221  
    222   '''Parameters:''' 
    223     '''path''' (optional): The directory path that will be used for extraction. If this is a user file, this would be the relative path from the user directory that was specified during the compilation of the library. If path is NULL, then it is ignored, with only the file name parameter below being compared for a match.[[BR]] 
    224     '''name''': the filename, stripped of any path information.   
    225   '''Return value:''' 
    226     A boolean indicating whether the file is embedded within the current library binary. 
    227  
    228   '''Remarks:''' 
    229     The '''bool''' type is defined in libwdi.h. 
    230 }}} 
    231 |---------------- 
    232 [[BR]] 
    233  
    234 |---------------- 
    235 {{{#!td style="background: #eef" 
    236   '''int [=#wdi_create_list wdi_create_list](struct wdi_device_info** list, struct wdi_options_create_list* options)''' 
    237 }}} 
    238 |---------------- 
    239 {{{#!td 
    240   '''Synopsis:''' 
    241     Create a '''struct wdi_device_info''' list of USB device currently present on the system. 
    242  
    243   '''Parameters:''' 
    244     '''list''': a pointer to a '''[#wdi_device_info struct wdi_device_info]*''' to act as the start of the list[[BR]] 
    245     '''options''': a pointer to a '''[#wdi_options_create_list struct wdi_options_create_list]''' or NULL for the default options.[[BR]] 
    246  
    247   '''Return value:''' 
    248     '''WDI_SUCCESS''' if the list of devices was successfully created.[[BR]] 
    249     '''WDI_ERROR_NO_DEVICE''' if the list is empty (*list will also be set to NULL).[[BR]] 
    250     '''WDI_ERROR_RESOURCE''' if memory could not be allocated internally.[[BR]] 
    251     '''WDI_ERROR_BUSY''' if another instance of this function call is in process.[[BR]] 
    252  
    253   '''Remarks:''' 
    254     If you want to list all USB devices, make sure you provide a valid wdi_options pointer, with list_all set to true. 
    255 }}} 
    256 |---------------- 
    257 [[BR]] 
    258  
    259 |---------------- 
    260 {{{#!td style="background: #eef" 
    261   '''int [=#wdi_destroy_list wdi_destroy_list](struct wdi_device_info* list)''' 
    262 }}} 
    263 |---------------- 
    264 {{{#!td 
    265   '''Synopsis:''' 
    266     Frees the '''struct wdi_device_info''' list returned by '''wdi_create_list''' 
    267  
    268   '''Parameters:''' 
    269     '''list''': a pointer to the first '''[#wdi_device_info struct wdi_device_info]''' device in the list 
    270  
    271   '''Return value:''' 
    272     '''WDI_SUCCESS''' if the list of devices was successfully destroyed.[[BR]] 
    273     '''WDI_ERROR_BUSY''' if another instance of this function call is in process. 
    274  
    275 }}} 
    276 |---------------- 
    277 [[BR]] 
    278  
    279 |---------------- 
    280 {{{#!td style="background: #eef" 
    281   '''int [=#wdi_create_inf wdi_prepare_driver](struct wdi_device_info* device_info, char* path, char* inf_name, struct wdi_options_prepare_driver* options)''' 
    282 }}} 
    283 |---------------- 
    284 {{{#!td 
    285   '''Synopsis:''' 
    286     Extract the driver files, and, where applicable, create the relevant inf for a specific device. 
    287  
    288   '''Parameters:''' 
    289     '''device_info''': a pointer to the '''[#wdi_device_info struct wdi_device_info]''' device to create the inf for[[BR]] 
    290     '''path''': the directory where the inf and driver files should be created[[BR]] 
    291     '''inf_name''': the name of the inf to generate (including the .inf extension)[[BR]] 
    292     '''options''': a pointer to a '''[#wdi_options_prepare_driver struct wdi_options_prepare_driver]''' or NULL for the default options.[[BR]] 
    293  
    294   '''Return value:''' 
    295     '''WDI_SUCCESS''' if the driver files were successfully extracted (WDI_USER) and the inf file was successfully generated (WDI_WINUSB, WDI_LIBUSB only).[[BR]] 
    296     '''WDI_ERROR_INVALID_PARAM''' if either one of the parameters is NULL or if driver_type is invalid.[[BR]] 
    297     '''WDI_ERROR_NOT_FOUND''' if the device_info is missing a description string or if the library is missing driver files.[[BR]] 
    298     '''WDI_ERROR_ACCESS''' if the destination directory, the inf file, or any of the required subdirectories for extraction, cannot be accessed or created.[[BR]] 
    299     '''WDI_ERROR_BUSY''' if another instance of this function call is in process. 
    300  
    301   '''Remarks:''' 
    302     If driver type is '''WDI_USER''', the device_info and inf_name paramaters are ignored and the driver files are extracted only. An inf is not generated in this case.[[BR]] 
    303     To find out more about the use of user supplied driver files, please see the [wiki:libwdi_install libwdi installation and configuration guide].[[BR]] 
    304     Even if your application runs in elevated mode, the driver files and directories will be owned by the user who launched the application.[[BR]] 
    305     If you provide a vendor_name in the options, this name will be used for the [Manufacturer] section of the inf. If not, prepare_driver() will try to resolve the vendor name according to the VID. 
    306 }}} 
    307 |---------------- 
    308 [[BR]] 
    309  
    310 |---------------- 
    311 {{{#!td style="background: #eef" 
    312   '''int [=#wdi_install_driver wdi_install_driver](struct wdi_device_info* device_info, char* path, char* inf_name, struct wdi_options_install_driver* options)''' 
    313 }}} 
    314 |---------------- 
    315 {{{#!td 
    316   '''Synopsis:''' 
    317     Perform the actual driver installation using the inf file named '''inf_name''' and driver files located in the directory pointed by '''path'''. 
    318  
    319   '''Parameters:''' 
    320     '''device_info''': a pointer to the '''[#wdi_device_info struct wdi_device_info]''' device to install the driver for[[BR]] 
    321     '''path''': the directory where the driver and inf files are located created[[BR]] 
    322     '''inf_name''': the name of the inf file to use for installation (including the .inf extension)[[BR]] 
    323     '''options''': a pointer to a '''[#wdi_options_install_driver struct wdi_options_install_driver]''' or NULL for the default options. If a HWND handle to a Windows application is provided as an option, a progress dialog will be displayed[[BR]] 
    324  
    325   '''Return value:''' 
    326     '''WDI_SUCCESS''' if the driver was installed successfully.[[BR]] 
    327     '''WDI_ERROR_INVALID_PARAM''' if either one of the parameters is NULL or the path to the inf file is invalid.[[BR]] 
    328     '''WDI_ERROR_PENDING_INSTALLATION''' if another driver installation is pending by the OS.[[BR]] 
    329     '''WDI_ERROR_RESOURCE''' if the pipe and associated event to communicate with the installer process could not be created.[[BR]] 
    330     '''WDI_ERROR_NOT_FOUND''' if the installer executable process (32 or 64 bit) could not be accessed or the inf file could not be opened.[[BR]] 
    331     '''WDI_ERROR_NEEDS_ADMIN''' if the installer executable process could not be run with necessary rights on platforms with UAC.[[BR]] 
    332     '''WDI_ERROR_WOW64''' if a 32 bit driver installation is attempted on a 64 bit environment.[[BR]] 
    333     '''WDI_ERROR_TIMEOUT''' if the installer executable process failed to answer in the allocated time.[[BR]] 
    334     '''WDI_ERROR_NOT_FOUND''' if the installer executable process sent a message that was unrecognised.[[BR]] 
    335     '''WDI_ERROR_EXISTS''' if the existing driver cannot be overwritten.[[BR]] 
    336     '''WDI_ERROR_INF_SYNTAX''' if the inf file is not properly formatted.[[BR]] 
    337     '''WDI_ERROR_UNSIGNED''' if the system policy has been modified from Windows defaults, and is set to reject unsigned drivers.[[BR]] 
    338     If this occurs on Windows XP, you might want to revert the driver installation policy to default.[[BR]] 
    339     See [http://articles.techrepublic.com.com/5100-10878_11-5875443.html][[BR]] 
    340     '''WDI_ERROR_CAT_MISSING''' if a cat file is required and cannot be located.[[BR]] 
    341     '''WDI_ERROR_USER_CANCEL''' if the user cancelled the installation process after an UAC prompt.[[BR]] 
    342     '''WDI_ERROR_OTHER''' for unhandled errors from the installer executable process.[[BR]] 
    343     '''WDI_ERROR_BUSY''' if another instance of this function call is in process. 
    344     
    345 }}} 
    346 |---------------- 
    347 [[BR]] 
    348  
    349 |---------------- 
    350 {{{#!td style="background: #eef" 
    351   '''int [=#wdi_install_trusted_certificate wdi_install_trusted_certificate](char* cert_name, struct wdi_options_install_cert* options)''' 
    352 }}} 
    353 |---------------- 
    354 {{{#!td 
    355   '''Synopsis:''' 
    356     Installs or updates the certificate '''cert_name''' into the system's Trusted Publisher store. This call must be run from an application running with elevated privileges on platforms with UAC. 
    357  
    358   '''Parameters:''' 
    359     '''cert_name''': a string identifying the embedded certificate file to use. If two certificate files with the same name have been embedded, in different locations, only the first one found will be used[[BR]] 
    360     '''options''': a pointer to a '''[#wdi_options_install_cert struct wdi_options_install_cert]''' or NULL for the default options. Unless the disable_warning option is provided, a warning will be displayed before a new certificate is installed or an existing one renewed.[[BR]] 
    361  
    362   '''Return value:''' 
    363     '''WDI_SUCCESS''' if the certificate was installed successfully.[[BR]] 
    364     '''WDI_ERROR_EXISTS''' if an identical certificate already exists in the store.[[BR]] 
    365     '''WDI_ERROR_INVALID_PARAM''' if the name of the certificate is invalid.[[BR]] 
    366     '''WDI_ERROR_NOT_FOUND''' if the certificate could not be located in the embedded files.[[BR]] 
    367     '''WDI_ERROR_NEEDS_ADMIN''' if the application is not running with the required privileges on platforms with UAC.[[BR]] 
    368     '''WDI_ERROR_ACCESS''' if the application is unable to access the system store or create a certificate context.[[BR]] 
    369     '''WDI_ERROR_RESOURCE''' if some of the resources required for installation are unavailable (crypt32.dll, etc).[[BR]] 
    370     '''WDI_ERROR_USER_CANCEL''' if the user cancelled the installation process after an UAC prompt. 
    371 }}} 
    372 |---------------- 
    373 [[BR]] 
    374  
    375 |---------------- 
    376 {{{#!td style="background: #eef" 
    377   '''int [=#wdi_set_log_level wdi_set_log_level](int level)''' 
    378 }}} 
    379 |---------------- 
    380 {{{#!td 
    381   '''Synopsis:''' 
    382     Sets the logging output level. Log messages are sent either to stderr (in console application mode) or to the registered logger (see below). 
    383  
    384   '''Parameters:''' 
    385     '''level''': can be one of '''WDI_LOG_LEVEL_DEBUG''', '''WDI_LOG_LEVEL_INFO''', '''WDI_LOG_LEVEL_WARNING''', '''WDI_LOG_LEVEL_ERROR''', '''WDI_LOG_LEVEL_NONE''', as defined in libwdi.h. 
    386  
    387   '''Return value:''' 
    388     '''WDI_SUCCESS''' if the level was successfully set.[[BR]] 
    389     '''WDI_ERROR_NOT_SUPPORTED''' if the library was compiled with forced debug. 
    390  
    391   '''Remarks:''' 
    392     Setting the log to a lower value than WDI_LOG_LEVEL_DEBUG or greater than WDI_LOG_LEVEL_NONE has the same affect as setting the level to WDI_LOG_LEVEL_DEBUG or WDI_LOG_LEVEL_NONE respectively. 
    393  
    394 }}} 
    395 |---------------- 
    396 [[BR]] 
    397  
    398 |---------------- 
    399 {{{#!td style="background: #eef" 
    400   '''int [=#wdi_register_logger wdi_register_logger](HWND hWnd, UINT message, DWORD buffsize)''' 
    401 }}} 
    402 |---------------- 
    403 {{{#!td 
    404   '''Synopsis:''' 
    405     Register a Window as destination for logging messages. This Window will be notified with a message event and should call '''wdi_read_logger()''' to retreive the message data. 
    406  
    407   '''Parameters:''' 
    408     '''hWnd''': the handle of the Window that should receive log notification messages. 
    409     '''message''': the value of the message ID that the logger should send back to the Window when log data is available. 
    410     '''buffsize''': the size to use for the internal log buffer. 0 will use the default size (8192 bytes). 
    411  
    412   '''Return value:''' 
    413     '''WDI_SUCCESS''' if the logger was successfully registered.[[BR]] 
    414     '''WDI_ERROR_EXISTS''' if a logger has already been registered.[[BR]] 
    415     '''WDI_ERROR_BUSY''' if another instance of this function call is in process. 
    416  
    417   '''Remarks:''' 
    418     Only one Window can be registered to receive logging messages at any one time.[[BR]] 
    419     While the buffer size is increased as needed from the one provided as parameter, if you don't read the log regularly when notified, internal logging can become a blocking operation if buffer resizing is needed. 
    420     The WPARAM parameter of Windows message indicates the log severity as per the '''wdi_log_level''' enum values found in libwdi.h. 
    421 }}} 
    422 |---------------- 
    423 [[BR]] 
    424  
    425 |---------------- 
    426 {{{#!td style="background: #eef" 
    427   '''int [=#wdi_unregister_logger wdi_unregister_logger](HWND hWnd)''' 
    428 }}} 
    429 |---------------- 
    430 {{{#!td 
    431   '''Synopsis:''' 
    432     Unregister a Window that was previously registered as destination for logging messages. 
    433  
    434   '''Parameters:''' 
    435     '''hWnd''': the handle of the Window that was set to handle logging messages. 
    436  
    437   '''Return value:''' 
    438     '''WDI_SUCCESS''' if the logger was successfully unregistered.[[BR]] 
    439     '''WDI_ERROR_INVALID_PARAM''' if '''hWnd''' does not match the one from the current logger destination.[[BR]] 
    440     '''WDI_ERROR_BUSY''' if another instance of this function call is in process. 
    441 }}} 
    442 |---------------- 
    443 [[BR]] 
    444  
    445 |---------------- 
    446 {{{#!td style="background: #eef" 
    447   '''int [=#wdi_read_logger wdi_read_logger](char* buffer, DWORD buffer_size, DWORD* message_size)''' 
    448 }}} 
    449 |---------------- 
    450 {{{#!td 
    451   '''Synopsis:''' 
    452     Reads a log message (following a notification received by a registered window) 
    453  
    454   '''Parameters:''' 
    455     '''buffer''': destination buffer.[[BR]] 
    456     '''buffer_size''': destination buffer size.[[BR]] 
    457     '''message_size''': pointer to the value receiving the actual length of the message received 
    458  
    459   '''Return value:''' 
    460     '''WDI_SUCCESS''' if a log message was successfully read.[[BR]] 
    461     '''WDI_ERROR_NOT_FOUND''' if no logger could be registered.[[BR]] 
    462     '''WDI_ERROR_IO''' if the log message could not be read.[[BR]] 
    463     '''WDI_ERROR_BUSY''' if another instance of this function call is in process.[[BR]] 
    464     '''WDI_ERROR_OVERFLOW''' if the provided buffer is too small. In this case, the original message is lost. 
    465  
    466   '''Remarks:''' 
    467     All logging data is UTF-8. 
    468 }}} 
    469 |---------------- 
    470 [[BR]] 
    471  
    472