Lightscribe Public Windows Software Development Kit

Transcription

1 Lightscribe Public Windows Software Development Kit About this Specification This document is the official Public LightScribe Software Development Kit (SDK) for Microsoft Windows. Hewlett-Packard (HP) reserves the right to provide updates or revisions to this specification. This document's purpose is to describe the components to be used by third-party independent software developers and vendors (ISVs) to support LightScribe Generation I optical disc media labeling. If the vendor wishes to use the LightScribe trademark they must submit the application for compliance testing and agree to the LightScribe Trademark Agreement. Prerequisites The LightScribe Direct Disc Labeling technology builds on existing industry standards for optical discs and hardware. This document assumes that readers are already familiar with these existing standards and that the products enabled with LightScribe Direct Disc Labeling technology are in full compliance with these standards. Legal Disclaimers and Licensing Claims Copyright Disclaimer (c) Copyright 2008 Hewlett-Packard Development Company, LP The LightScribe Software Requirements Specification is published by Hewlett-Packard Company (Palo Alto, CA, USA). All rights reserved. Reproduction in whole or in part is prohibited without express, prior written permission of HP. The information contained herein is believed to be accurate as of the date of publication. However, HP shall not be liable for any damages, including indirect or consequential, from use of the LightScribe Direct Disc Labeling System or reliance on the accuracy of this document. Version Information Version 3.0 September 6, 2008 In Version 3.0, the following changes were made. The LSPrintLauncher library has been deprecated in favor of the LSPrintAPI library. New users of the SDK should use the LSPrintAPI library. This document will describe the LSPrintAPI library and its functionality. Additional APIs were added to facilitate unattended, programmatic control of the printing. These APIs include: o get_drive_count()

2 o get_drive_path() o get_drive_display_name() o get_drive_status() o get_print_status() o abort_print() Additional command line options were added to the launch_printing_dialog() API to facilitate unattended, programmatic control of the printing. The enhanced launch_printing_dialog() options are used in conjunction with the new APIs indicated above. Version 2.0, February 6, 2008 In Version 2.0, the following changes were made. An additional API, havelsdrive(), was added to detect the presence of LightScribe drives. Version 1.0, January 3, 2008 Initial version. Page 2 of 23

3 Contents Lightscribe Public Windows Software Development Kit Introduction Architecture and Usage of LightScribe Printing Components API Usage Scenarios Print Options Dialog Details Major Features of Print Options Dialog Printing Dialog Details Major Features of Printing Dialog Localization Help System Library Usage Library Footprint Linking/Library Loading Library Detection Library Versioning Strategy LightScribe Software Update Mechanism Application Installation Requirements Sample code LSPrintAPI Library API Definition launch_print_options_dialog launch_printing_dialog have_lightscribe_drive get_drive_count get_drive_path get_drive_display_name get_drive_status get_print_status abort_print Page 3 of 23

4 1 Introduction The goals of this Windows LightScribe Software Development Kit are to: Provide a short learning curve on the LightScribe interfaces with no need to understand the nuances of LightScribe technology. Simplify the development of the LightScribe portion of application code. Standardize the application user interface for LightScribe use. Retain the ability to introduce new features to the LightScribe System Software (LSS) without impacting existing applications. Eliminate complex licensing processes, enabling individual developers to develop LightScribe applications. Minimize test requirements for the LightScribe labeling functionality. Provide troubleshooting documentation on the LightScribe printing functionality. Support localized applications for most common languages. In a disc labeling application, three main pieces of functionality exist: 1. The Label Designer 2. The Print Options dialog 3. The Printing (or Print Progress) dialog. This SDK provides access to the 2 nd and 3 rd pieces of functionality. The actual components are distributed as part of the LightScribe System Software Version and onwards. The software components provide almost all of the standard functionality a LightScribe labeling application needs to support LightScribe printing. It provides a simple way for an application to be enabled for LightScribe labeling. 1.1 Architecture and Usage of LightScribe Printing Components Applications do not interact directly with the LightScribe Printing Components. Instead, the components are accessed via a C DLL. The LSPrintAPI dynamic link library is used to access and communicate with the LightScribe drives, get information about the drives, create the user interface components, send label printing jobs to the LightScribe drives, and monitor print job progress. The LSPrintAPI creates two main user interface components as standalone processes: LSPrintDialog.exe and LSPrintingDialog.exe. These LightScribe printing dialogs may be utilized to provide a standardized LightScribe user experience. 1.2 API Usage Scenarios The LSPrintAPI SDK provides a rich interface for application developers to use to print labels using LightScribe drives. Applications typically follow one of the following use models. Page 4 of 23

5 Standard Usage: In this usage model, the application launches the Print Options Dialog (using the launch_print_options_dialog API). This dialog box provides the user with options to initiate printing of a label to a LightScribe drive. Once the user selects the Print button on the dialog, the print will begin and the Printing Dialog will be displayed to provide monitoring of the print progress. Applications should, in general, only interact with the Print Options Dialog (using the launch_print_options_dialog API) rather than the Printing Dialog (using the launch_printing_dialog API). The Printing Dialog is available to support direct printing without requiring user interaction to select the print options. A sample application, ImageBurner2, is included in the SDK to illustrate this usage model. Programmatic Usage: In this usage model, the application gets the drive count and then iterates through the number of drives to get the path, name, and status of each drive. These values are then used to launch a print to a specific drive via the Printing Dialog (using the launch_printing_dialog API). By default the Printing Dialog will appear and pop-up dialogs will be displayed as necessary to resolve error conditions. The Printing Dialog can be minimized with the noshow command line option. The pop-up dialogs can be suppressed with the nooperator option. The application can then monitor the status of print jobs using theget_print_status() API. If necessary the application can abort a print in progress with theabort_print() API. A sample application, AutoPrint, is included in the SDK to illustrate this usage model. Command Line Usage: In general, using the library interface is the preferred approach. However, it is possible to run the underlying exe files directly from the command line or a script, Please be aware that future changes to these components may affect the ability to execute them from the command line. In this mode of use, the dialogs are launched directly and given command-line parameters. The command line options are the same as used by the LSPrintAPI library. Thelaunch_print_options_dialog function corresponds to LSPrintDialog.exe, and launch_printing_dialog function corresponds to LSPrintingDialog.exe. For example: LSPrintingDialog.exe --filename "C:/TestImage.bmp" --name "ASUS DRW- 1612BLT (F:)" --index 0 --quality best --path F --copies 1 -- media 1 --deleteimagefile 1 Page 5 of 23

6 1.3 Print Options Dialog Details The Print Options dialog is what the user traditionally sees when Print is selected in the labeling application. Below is a screenshot of the LightScribe Print Options dialog component Major Features of Print Options Dialog The drive enumeration and status and print preview operations are performed in separate threads, resulting in up-to-date information and a UI that is responsive during these time-consuming activities. LightScribe media is available in multiple colors; the print preview can be generated in the available colors to give a realistic impression of how the labeled disc will look if printed on a colored disc rather than the classic LightScribe disc. The print preview is rendered to give an approximate representation of the contrast level that will be provided with a given Contrast Level selection. A print time estimate is given to give an approximate representation of the time it will take to print the image. This time is computed using information about the drive s capabilities and the Contrast Level selection. Fully localized standard UI and user messaging. Developed with a full understanding of the nuances of the LightScribe technology and System Software. Page 6 of 23

7 1.4 Printing Dialog Details The Printing or Burn Progress dialog is what the user traditionally sees during printing. Below is a screenshot of the LightScribe Printing dialog component Major Features of Printing Dialog Simulated real-time graphical view of the print progress Fully localized standard UI and user messaging. Developed with a full understanding of the nuances of the LightScribe technology and System Software. 1.5 Localization The LightScribe Printing Components are localized into these languages: Page 7 of 23

8 Primary Language 3-LA LangID (dec) Arabic ARA 1025 Chinese Simplified CHS 2052 Chinese Traditional CHT 1028 Czech CSY 1029 Danish DAN 1030 Dutch NLD 1043 Finnish FIN 1035 French FRA 1036 German DEU 1031 Greek ELL 1032 Hebrew HEB 1037 Italian ITA 1040 Japanese JPN 1041 Korean KOR 1042 Norwegian NOR 1044 Polish PLK 1045 Portuguese PTB 1046 Portuguese PTG 2070 Russian RUS 1049 Slovak SKY 1051 Spanish ESN 1034 Swedish SVE 1053 Turkish TRK 1055 Page 8 of 23

9 The components are Microsoft Multilingual User Interface (MUI) enabled, so they will detect which display language to use. Because of this, if the OS is running in one language, but the user has set the Display Language to another language, the components may be running in a different language than the application if the application is not MUI enabled and thus is not reading the Display Language. 1.6 Help System The application s help content is not required to include detailed help relating to the LightScribe printing functionality, but a basic walkthrough on printing a LightScribe disc is recommended. Detailed help files on the Print Options and Printing Dialogs are HTML files located in %CommonProgramFiles%\LightScribe\Content\help\<Language TLA>, and the user can view these by clicking the Help button on the printing components. Page 9 of 23

10 2 Library Usage 2.1 Library Footprint The LightScribe Labeling Components Library consists of the following files: LSPrintAPI.dll dynamic link library LSPrintAPI.lib import library for linker LSPrintAPI.h header file with API LSPrintStatusCodes.h header file with print status codes 2.2 Linking/Library Loading Applications can use either build-time or run-time linking. To use build-time (or implicit) linking, add the LSPrintAPI.lib import library to your project linker settings and #include LSPrintAPI.h to your code. In order for this to work, the dll needs to be in the search path for loading dlls. This requires extra effort to read the location from the registry and add it to the path, so it is not the recommended approach. To use run-time (or explicit) linking, the library needs to be loaded with the Windows API LoadLibrary. Additionally, the functions may need to be resolved with the Windows API GetProcAddress passing in the function s name. This is the method used in the sample application. It also uses the /DELAYLOAD linker option to prevent Windows from trying to load the LSPrintAPI library upon startup of the application. When using this method, errors such as Library Not Found can be handled gracefully at runtime. Also, the library can be loaded only when needed and unloaded when not needed. This is demonstrated in the ImageBurner2 sample code function LSSDKHelper::LS_LoadLibrary. Note that the sample code is not production-ready code. 2.3 Library Detection At runtime startup, applications should check (stat) for the presence of the LSPrintAPI library. The absolute path and name of this dll is stored in the registry key HKLM\SOFTWARE\LightScribe\LSPrintAPI. This key should be read and the application should check for the existence of the filename it provides. This is demonstrated in the ImageBurner2 sample code function LSSDKHelper::LS_GetLibraryLocation. Note that the sample code is not productionready code. If this key is not present or the location it specifies cannot be loaded, a localized message should be display to inform the user that they need to install the latest version of the Page 10 of 23

11 LightScribe System Software with a button or link to Library Versioning Strategy For most Windows API functions, only the names are preserved across different Windows releases; the ordinals are subject to change. So, one cannot reliably import Windows API functions by their ordinals. Likewise, in this API, only the function names are guaranteed to be preserved across releases. Because of this, linking/resolving should be done using the function names rather than the ordinals. This will ensure backward compatibility of the library. NOTE: Applications should never install their own version of LSPrintAPI.dll (i.e. in the application s folder); instead they must use the version that is part of the LightScribe System Software using the Library Detection technique described above. 2.5 LightScribe Software Update Mechanism LightScribe technology is continually undergoing improvements and extensions, and it is important that the software on the user s system remains up-to-date. The updating of the LightScribe Software is normally handled by the LightScribe Print Options component. The application will only prompt for an update when one of the functions returns an error, or a problem occurs when loading the library. In this case, the application should direct the user to Application Installation Requirements The application installer should check for a version or greater LightScribe System Software at install time. The full LightScribe System Software version number is stored in the registry keyhklm/software/lightscribe/update/currentversion with a REG_SZ value. 2.7 Sample code The SDK includes two sample applications, ImageBurner2 and AutoPrint. ImageBurner2 illustrates using the API for the standard usage scenario (See Section 1.2). The AutoPrint sample application illustrates using the API for the programmatic usage scenario. These are not production quality code, but they show the basic function calls required to use the library for the two scenarios. The ImageBurner2 sample application code can be built using the ImageBurner2 Visual Studio 2005 project (ImageBurner2SDK.vcproj). The AutoPrint sample application code can be built using the AutoPrint Visual Studio project (AutoPrintSDK.vcproj). Also included is the LightScribeSDK folder which contains the files needed to use the API. These files must be copied to a suitable location for the application s build system. Note: Because the LightScribe System Software components are not included in the SDK, the developer must have the LightScribe System Software installed in order to test the application. Page 11 of 23

12 3 LSPrintAPI Library 3.1 API Definition Below is an excerpt from LSPrintAPI.h showing the API. The remainder of this section describes each API in detail. /** API entry point for launching the Print Options dialog. poptions The string consists of a list of options, each option is prefixed with "--".\n * The options string can have the following parameters:\n * "--version" or "--v" : Displays the version dialog\n * "--help" or "--h" : Display dialog with description of the API for the developer (not intended for end-user)\n * "--filename" or "--f" : Source image file name (string)\n * "--deleteimagefile" or "--d" : Automatically delete source file (boolean, default value = "false" ("0"))\n 0 = Success, other error codes as per winerror.h */ LSPRINTAPI_EXPORT int launch_print_options_dialog(const wchar_t* poptions); /** API entry point for launching the Printing dialog. poptions The string consists of a list of options, each option is prefixed with "--".\n * The options string can have the following parameters:\n * "--version" or "--v" : Displays the version dialog\n * "--help" or "--h" : Display dialog with description of the API for the developer (not intended for end-user)\n * "--filename" or "--f" : Image file name (string)\n * "--index" or "--i", : Drive index (unsigned int)\n * "--name" or "--n" : Drive name (string)\n * "--quality" or "--q" : Label quality (string - "draft"/"normal"/"best", default value = "normal")\n * "--path" : Drive path (string)\n * "--copies" or "--c" : Number of copies (unsigned int, default value = "1")\n * "--targetfile" or " t" : Print to file target file name (string)\n * "--media" or "--m" : Media already detected (bool, default value = "1")\n * "--deleteimagefile" or "--d" : Automatically delete source file (bool, default value = "false" ("0"))\n * "--autoclose" or "--a" : Close dialog when print completes (bool, default value = "false" ("0"))\n * "--noshow" or "--s" : Hide dialog during printing (bool, default value = "false" ("0"))\n * "--autoeject" or "--e" : Automatically open tray when print completes (bool, default value = "true" ("1"))\n * "--usegeneric" or "--g" : Don't prompt if generic printing is intended (bool, default value = "false" ("0"))\n * "--nooperator" or "--o" : Unattended mode of operation with no user interface interactions (bool, default value = "false" ("0"))\n 0 = Success, other error codes as per winerror.h */ LSPRINTAPI_EXPORT int launch_printing_dialog(const wchar_t* poptions); /** These constant definitions are used by the PrintInfo related API's **/ const int LS_SUCCESS = 0; /* success */ const int LS_FAILURE = 1; /* unknown failure */ const int LS_INVALID_DRIVE_INDEX = 2; /* Drive index number is not within the range of valid drives */ const int LS_INVALID_ARRAY_SIZE = 3; /* Array size specified is too small for return value */ Page 12 of 23

13 /** API entry point for testing if there is a LightScribe drive on the system. * Note: This requires the LightScribe System Software to be installed. rhavedrive Output parameter: true = 1 or false = 0 LS_SUCCESS or other error codes as per LSPrintAPI.h */ LSPRINTAPI_EXPORT int have_lightscribe_drive(bool& rhavedrive); /** API entry point to get the number of LightScribe drive on the system. * Note: This requires the LightScribe System Software to be installed. rdrivecount Output parameter: Number of drives LS_SUCCESS or other error codes as per LSPrintAPI.h **/ LSPRINTAPI_EXPORT int get_drive_count(unsigned int& rdrivecount); /** API entry point to get the path name of a LightScribe drive. E.g. "D", "E"... * Note: This requires the LightScribe System Software to be installed. driveindex Index of drive. Drives are numbered from 0 to drivecount - 1. pdrivepath Output parameter: Name of the drive path drivepathsize Allocated size of the drive path array. LS_SUCCESS or other error codes as per LSPrintAPI.h **/ LSPRINTAPI_EXPORT int get_drive_path(const unsigned int driveindex, wchar_t* pdrivepath, const unsigned int drivepathsize); /** API entry point to get the name of a LightScribe drive. * Note: This requires the LightScribe System Software to be installed. driveindex Index of drive. Drives are numbered from 0 to drivecount - 1. pdrivedisplayname Output parameter: Display name of the drive drivedisplaynamesize The length, in number of characters, already allocated to pdrivedisplayname code: LS_SUCCESS or other error codes as per LSPrintAPI.h **/ LSPRINTAPI_EXPORT int get_drive_display_name(const unsigned int driveindex, wchar_t* pdrivedisplayname, const unsigned int drivedisplaynamesize); /** API entry point to get the current status of a LightScribe drive. * Note: This requires the LightScribe System Software to be installed. driveindex index of drive. Drives are numbered from 0 to drivecount - 1. rdrivestatus Output parameter: Current status of the drive. code: LS_SUCCESS or other error codes as per LSPrintAPI.h **/ enum LSDriveStatus {LS_DRIVE_STATUS_AVAILABLE, LS_DRIVE_STATUS_ERROR, LS_DRIVE_STATUS_UPDATE, LS_DRIVE_STATUS_BUSY, LS_DRIVE_STATUS_UNKNOWN }; LSPRINTAPI_EXPORT int get_drive_status(const unsigned int driveindex, LSDriveStatus& rdrivestatus); /** API entry point to get the current print status. * Note: This requires the LightScribe System Software to be installed. driveindex Index of drive. Drives are numbered from 0 to drivecount - 1. rprintstatuscode Output parameter: Print status code. rcurrentcopyno Output parameter: Number of the current copy being printed. rtotalnoofcopies Output parameter: Total number of copies to print. rpercentcomplete Output parameter: Percentage of the print job completed on the given drive. restimatedtimeremainingsecs Output parameter: Estimated time remaining in seconds. pprintstatusstring Output parameter: Print status string. printstatusstringsize: Allocated size of the print status array. Page 13 of 23

14 pestimatedtimeremainingstring Output parameter: Estimated time remaining string. estimatedtimeremainingstringsize: Allocated size of the estimated time remaining array. code: LS_SUCCESS or other error codes as per LSPrintAPI.h **/ LSPRINTAPI_EXPORT int get_print_status(const unsigned int driveindex, LSPrintStatusCode& rprintstatuscode, unsigned int& rcurrentcopyno, unsigned int& rtotalnoofcopies, unsigned int& rpercentcomplete, unsigned int& restimatedtimeremainingsecs, wchar_t* pprintstatusstring, const unsigned int printstatusstringsize, wchar_t* pestimatedtimeremainingstring, const unsigned int estimatedtimeremainingstringsize); /** API entry point to request the current print be aborted. * Note: This requires the LightScribe System Software to be installed. * Note: The current implementation of this function returns after requesting the * print be aborted. It does not wait for the abort to complete. The application * should continue to monitor the print status with "get_print_status()" until * a canceled status is returned from that function. * This behavior may change in a future release. driveindex index of drive. Drives are numbered from 0 to drivecount - 1. code: LS_SUCCESS or other error codes as per LSPrintAPI.h **/ LSPRINTAPI_EXPORT int abort_print(const unsigned int driveindex); Page 14 of 23

15 3.2 launch_print_options_dialog Definition: int launch_print_options_dialog(const wchar_t* poptions); Input Parameter(s): ThepOptions argument is a C string with classic command line style parameters. Each option has a long version and a short version. The long versions are preceded with a double dash, --", and the short versions by a single dash, -. Some options require a value, while others have no associated value but are parsed for their presence or nonpresence only. version Using this (optional) option will display a dialog with the version number of the component. This is intended to be used by developers only; i.e. not in application code. This parameter has no value associated with it. help - Using this (optional) parameter will display a dialog with the command parameters described. This is intended to be used by developers only. ; i.e. not in application code. This parameter has no value associated with it. deleteimagefile This (optional) parameter allows the client to either keep or hand-off ownership of the source image file. This is useful for the case where a temporary bmp file was created by the application for passing the LightScribe Print Component. In this case, the LightScribe Print Component would know it should delete the source file and prevent needlessly wasting storage space with the temporary file. When using "-d 0" it is important that the application does not delete the file from underneath the printing component. Hence, the recommended approach is for the application to use "-d 1" as a command line argument. This will transfer ownership of the file to the printing component, which will delete it when it is finished. In combination with -d 1, it is recommended that the bitmap file passed in be a uniquely named file stored in the user s temp folder (usually C:\Documents and Settings\<user name>\local Settings\Temp). This is demonstrated in the ImageBurner2 sample code function CBitmapView::OnLightScribePrint(). This parameter has a boolean value associated with it. The default value is 0. filename This (required) parameter is used to specify the filename of the source image that is to be labeled. It should be a full path to the source bitmap. This parameter has a string value associated with it. There is no default value. Output Parameter(s): None Page 15 of 23

16 Return Codes: The return codes for this API are the standard Windows error codes defined in the Platform SDK file winerror.h. Therefore a return code of 0 (ERROR_SUCCESS) is returned upon a successful function execution. 3.3 launch_printing_dialog Definition: int launch_printing_dialog(const wchar_t* poptions); Input Parameter(s): ThepOptions argument is a C string with classic command line style parameters. Each option has a long version and a short version. The long versions are preceded with an double dash, --", and the short versions by a single dash, -. Some options require a value, while others have no associated value but are parsed for their presence or nonpresence only. version Using this (optional) option will display a dialog with the version number of the component. This is intended to be used by developers only; i.e. not in application code. This parameter has no value associated with it. help - Using this (optional) parameter will display a dialog with the command parameters described. This is intended to be used by developers only. ; i.e. not in application code. This parameter has no value associated with it. deleteimagefile This (optional) parameter allows the client to either keep or hand-off ownership of the source image file. This is useful for the case where a temporary bmp file was created by the application for passing the LightScribe Print Component. In this case, the LightScribe Print Component would know it should delete the source file and prevent needlessly wasting storage space with the temporary file. When using "-d 0" it is important that the application does not delete the file from underneath the printing component. Hence, the recommended approach is for the application to use "-d 1" as a command line argument. This will transfer ownership of the file to the printing component, which will delete it when it is finished. In combination with -d 1, it is recommended that the bitmap file passed in should be a uniquely named file stored in the user s temp folder (usually C:\Documents and Settings\<user name>\local Settings\Temp). This is demonstrated in the ImageBurner2 sample code function -CBitmapView::OnLightScribePrint(). This parameter has a boolean value associated with it. The default value is 0. filename This (required) parameter is used to specify the filename of the source image that is to be labeled. It should be a full path to the source bitmap. It is recommended that the bitmap file passed in should be a uniquely named file stored in the user s temp Page 16 of 23

17 folder (usually C:\Documents and Settings\<user name>\local Settings\Temp). This would be used in combination with the deleteimagefile parameter. We also recommend that the file s name has the prefix ls_. This parameter has a string value associated with it. There is no default value. index This (required) parameter is used to select drive to print on. It is a zero-based logical LightScribe drive number. The numbers are assigned in alphabetical order of the drive letter. i.e. if there are 3 LightScribe enabled drives with drive letters E, G & K, they would have indexes 0, 1 & 2 respectively. This parameter has an unsigned integer value associated with it. The default value is 0. name This (required) parameter specifies the drive name. It is used only as a display string in the GUI, not as the drive selection. This parameter has a string value associated with it. There is no default value. quality This (required) parameter specifies the contrast level setting to use in this print. This parameter has a string value associated with it. The default value is best. Other possible values are normal and draft. path This (required) parameter specifies the path of the selected logical LightScribe drive. On Windows should be a drive letter better A to Z. The drive path must match the actual path of the selected logical LightScribe drive. i.e. if there are 3 LightScribe enabled drives, E, F & K, they are normally drive indexes 0, 1 & 2 respectively. So, in this case, using the parameters --index 0 --path E would be correct; whereas --index 1 --path E would be an incorrect combination and generate an error. This parameter has a string value associated with it. There is no default value. copies This (optional) parameter specifies how many copies of a disc to print. This parameter has an unsigned integer value associated with it. The default value is 1. targetfile This (optional) parameter can be used to specify an output file for the LightScribe System Software to create. Using this parameter will invoke a print to file mode. This is currently for test purposes only. This parameter has a string value associated with it. There is no default value. media This (optional) parameter specifies whether media is known to be in the tray already. If this value is 0, then the tray will be ejected and the user will be prompted to insert media (even if there actually is LightScribe media loaded). If the value is 1, the software will attempt to print to the drive (closing the tray if necessary). This parameter has a boolean value associated with it. The default value is 1. autoclose This (optional) parameter specifies that the printing dialog shall automatically close without user interaction. The default value is 0. Page 17 of 23

18 noshow This (optional) parameter specifies that the printing dialog shall operate in the background (minimized). Any pop-up dialogs will be presented unless suppressed with the nooperator option. The default value is 0. autoeject This (optional) parameter specifies that the tray should be opened when the print completes. If set to false ( 0 ) the tray will remain closed when the print completes. The default value is true ( 1 ). usegeneric This (optional) parameter specifies that generic printing values should be used if optimal printing values are not supported. If optimal printing values are not supported for the target drive the printing dialog will, by default, prompt the user to choose to use either generic printing or update the system software. This parameter can be used to prevent the prompt and inform the printing dialog to use generic printing values in this situation. Printing will continue without prompting the user. The default value is false ( 0 ). nooperator This (optional) parameter indicates there is no operator present to respond to GUI dialogs. All pop-up dialogs will be suppressed. If an error occurs that would normally cause a dialog to be presented, the print will terminate and an error code will be returned. The default value is false ( 0 ). Output Parameter(s): None Return Codes: The return codes for this API are the standard Windows error codes defined in the Platform SDK file winerror.h. Therefore a return code of 0 (ERROR_SUCCESS) is returned upon a successful function execution. 3.4 have_lightscribe_drive Definition: int have_lightscribe_drive(bool &rhavedrive); Input Parameter(s): None Page 18 of 23

19 Output Parameter(s): rhavedrive This parameter returns the value true if there is a LightScribe drive on the system and false otherwise. Return Codes: This function returns a LightScribe Error Code as described in LSPrintAPI.h. On success, the function returns LS_SUCCESS. 3.5 get_drive_count Definition: int get_drive_count(unsigned int &rdrivecount) Input Parameter(s): None Output Parameter(s): rdrivecount The number of LightScribe drives in the system. The LightScribe drives are numbered from 0 to drivecount -1. Return Codes: This function returns a LightScribe Error Code as described in LSPrintAPI.h. On success, the function returns LS_SUCCESS. 3.6 get_drive_path Definition: int get_drive_path(const unsigned int driveindex, wchar_t *pdrivepath, const unsigned int drivepathsize) Input Parameter(s): driveindex The index number of a LightScribe drive. LightScribe drives are numbered from 0 to drivecount 1. drivepathsize The length, in number of characters, already allocated to pdrivepath. Page 19 of 23

20 Output Parameter(s): pdrivepath The path name of the LightScribe drive with the given index number. The path name is assigned by the operating system. Return Codes: This function returns a LightScribe Error Code as described in LSPrintAPI.h. On success, the function returns LS_SUCCESS. 3.7 get_drive_display_name Definition: int get_drive_display_name(const unsigned int driveindex, wchar_t *pdrivedisplayname, const unsigned int displaynamesize) Input Parameter(s): driveindex The index number of a LightScribe drive. LightScribe drives are numbered from 0 to drivecount 1. displaynamesize The length, in number of characters, already allocated to pdrivedisplayname. Output Parameter(s): pdrivedisplayname The display name of the LightScribe drive with the given index number. Return Codes: This function returns a LightScribe Error Code as described in LSPrintAPI.h. On success, the function returns LS_SUCCESS. 3.8 get_drive_status Definition: enum LSDriveStatus {LS_DRIVE_STATUS_AVAILABLE, LS_DRIVE_STATUS_ERROR, LS_DRIVE_STATUS_UPDATE, LS_DRIVE_STATUS_BUSY, LS_DRIVE_STATUS_UNKNOWN }; int get_drive_status(const unsigned int driveindex, LSDriveStatus& rlsdrivestatus) Page 20 of 23

21 Input Parameter(s): driveindex The index number of a LightScribe drive. LightScribe drives are numbered from 0 to drivecount 1. Output Parameter(s): rdrivestatus One of the LSDriveStatus enumerated values. Return Codes: This function returns a LightScribe Error Code as described in LSPrintAPI.h. On success, the function returns LS_SUCCESS. 3.9 get_print_status Definition: enum LSPrintStatusCode {LS_PRINT_STATUS_UNAVAILABLE, LS_PRINT_STATUS_STARTING, LS_PRINT_STATUS_PREPARING, LS_PRINT_STATUS_DETECTING, LS_PRINT_STATUS_DRIVE_START_UP, LS_PRINT_STATUS_PRINTING, LS_PRINT_STATUS_COMPLETE, LS_PRINT_STATUS_CANCELED, LS_PRINT_STATUS_CANCELING, LS_PRINT_STATUS_GENERIC_ERROR }; int get_print_status(const unsigned int driveindex, LSPrintStatusCode& rprintstatuscode, unsigned int& rcurrentcopyno, unsigned int& rtotalnoofcopies, unsigned int& rpercentcomplete, unsigned int& restimatedtimeremainingsecs, wchar_t* pprintstatusstring, const unsigned int printstatusstringsize, wchar_t* pestimatedtimeremainingstring, const unsigned int estimatedtimeremainingstringsize) Input Parameter(s): driveindex The index number of a LightScribe drive. LightScribe drives are numbered from 0 to drivecount 1. printstatusstringsize - The length, in number of characters, already allocated to rprintstatusstring. estimatedtimeremainingstringsize - The length, in number of characters, already allocated to restimatedtimeremaining. Page 21 of 23

22 Output Parameter(s): rprintstatuscode One of the enumerated values from LSPrintStatusCode.h. This describes the current status of the print. rcurrentcopyno The current copy number being printed. rtotalnoofcopies The total number of copies requested to be printed. rpercentcomplete The percentage of the print completed on the current drive. restimatedtimeremainingsecs The estimated number of seconds remaining until the print completes. pprintstatusstring A displayable string indicating the current status of the print. pestimatedtimeremainingstring A displayable string indicating the estimated time remaining in minutes until the print completes. Return Codes: This function returns a LightScribe Error Code as described in LSPrintAPI.h. On success, the function returns LS_SUCCESS abort_print Note: The current implementation of this function returns after requesting the print be aborted. It does not wait for the abort to complete. The application should continue to monitor the print status with get_print_status()" until a canceled status is returned from that function. This behavior may change in a future release. Definition: int abort_print(const unsigned int driveindex) Input Parameter(s): driveindex The index number of a LightScribe drive. LightScribe drives are numbered from 0 to drivecount 1. Output Parameter(s): None. Page 22 of 23

23 Return Codes: This function returns a LightScribe Error Code as described in LSPrintAPI.h. On success, the function returns LS_SUCCESS. Page 23 of 23