LightScribe Public Windows SDK Documentation

Lightscribe Public Windows Software Development Kit

About this SpecificationThis document is the official Public LightScribe Software Development Kit (SDK) forMicrosoft Windows. Hewlett-Packard (HP) reserves the right to provide updates orrevisions to this specification.

This document's purpose is to describe the components to be used by third-partyindependent software developers and vendors (ISVs) to support LightScribe Generation Ioptical disc media labeling. If the vendor wishes to use the LightScribe trademark theymust submit the application for compliance testing and agree to the LightScribeTrademark Agreement.

PrerequisitesThe LightScribe Direct Disc Labeling technology builds on existing industry standards foroptical discs and hardware. This document assumes that readers are already familiarwith these existing standards and that the products enabled with LightScribe Direct DiscLabeling technology are in full compliance with these standards.

Legal Disclaimers and Licensing Claims

Copyright

(c) Copyright 2008 Hewlett-Packard Development Company, LP

The LightScribe Software Requirements Specification is published by Hewlett-PackardCompany (Palo Alto, CA, USA). All rights reserved. Reproduction in whole or in part isprohibited without express, prior written permission of HP.

Disclaimer

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 ofthis 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 LSPrintAPIlibrary. New users of the SDK should use the LSPrintAPI library. This documentwill describe the LSPrintAPI library and its functionality.

Additional APIs were added to facilitate unattended, programmatic control of theprinting. These APIs include:

o get_drive_count()

LightScribe Public Windows Software Development Kit (SDK)

Document Number: PWSDK Revision: 3, Date:12/10/2008 of 23

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() APIto facilitate unattended, programmatic control of the printing. The enhancedlaunch_printing_dialog() options are used in conjunction with the new APIsindicated 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 ofLightScribe drives.

Version 1.0, January 3, 2008

Initial version.



Contents

Lightscribe Public Windows Software Development Kit................................................... 11 Introduction................................................................................................................. 4

1.1 Architecture and Usage of LightScribe Printing Components............................. 41.2 API Usage Scenarios............................................................................................ 41.3 Print Options Dialog Details ................................................................................ 6

1.3.1 Major Features of Print Options Dialog........................................................ 61.4 Printing Dialog Details......................................................................................... 7

1.4.1 Major Features of Printing Dialog ................................................................ 71.5 Localization.......................................................................................................... 71.6 Help System ......................................................................................................... 9

2 Library Usage............................................................................................................ 102.1 Library Footprint ................................................................................................ 102.2 Linking/Library Loading.................................................................................... 102.3 Library Detection ............................................................................................... 102.4 Library Versioning Strategy............................................................................... 112.5 LightScribe Software Update Mechanism ......................................................... 112.6 Application Installation Requirements............................................................... 112.7 Sample code ....................................................................................................... 11

3 LSPrintAPI Library................................................................................................... 123.1 API Definition .................................................................................................... 123.2 launch_print_options_dialog.............................................................................. 153.3 launch_printing_dialog....................................................................................... 163.4 have_lightscribe_drive ....................................................................................... 183.5 get_drive_count.................................................................................................. 193.6 get_drive_path.................................................................................................... 193.7 get_drive_display_name..................................................................................... 203.8 get_drive_status.................................................................................................. 203.9 get_print_status .................................................................................................. 213.10 abort_print ...................................................................................................... 22



1 IntroductionThe goals of this Windows LightScribe Software Development Kit are to:

Provide a short learning curve on the LightScribe interfaces with no need tounderstand 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 Designer2. The Print Options dialog3. The Printing (or Print Progress) dialog.

This SDK provides access to the 2nd and 3rd pieces of functionality. The actualcomponents are distributed as part of the LightScribe System Software Version 1.10.19.1and onwards. The software components provide almost all of the standard functionality aLightScribe labeling application needs to support LightScribe printing. It provides asimple way for an application to be enabled for LightScribe labeling.

1.1 Architecture and Usage of LightScribe Printing ComponentsApplications do not interact directly with the LightScribe Printing Components. Instead,the components are accessed via a C DLL. The LSPrintAPI dynamic link library is usedto 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 interfacecomponents as standalone processes: LSPrintDialog.exe and LSPrintingDialog.exe.These LightScribe printing dialogs may be utilized to provide a standardized LightScribeuser experience.

1.2 API Usage ScenariosThe LSPrintAPI SDK provides a rich interface for application developers to use to printlabels using LightScribe drives. Applications typically follow one of the following usemodels.



Standard Usage:

In this usage model, the application launches the Print Options Dialog (using thelaunch_print_options_dialog API). This dialog box provides the user with options toinitiate printing of a label to a LightScribe drive. Once the user selects the Print buttonon the dialog, the print will begin and the Printing Dialog will be displayed to providemonitoring of the print progress.

Applications should, in general, only interact with the Print Options Dialog (using thelaunch_print_options_dialog API) rather than the Printing Dialog (using thelaunch_printing_dialog API). The Printing Dialog is available to support directprinting without requiring user interaction to select the print options.

A sample application, ImageBurner2, is included in the SDK to illustrate this usagemodel.

Programmatic Usage:

In this usage model, the application gets the drive count and then iterates through thenumber of drives to get the path, name, and status of each drive. These values are thenused to launch a print to a specific drive via the Printing Dialog (using thelaunch_printing_dialog API). By default the Printing Dialog will appear and pop-updialogs will be displayed as necessary to resolve error conditions. The Printing Dialogcan be minimized with the noShow command line option. The pop-up dialogs can besuppressed with the noOperator option. The application can then monitor the status ofprint jobs using the get_print_status() API. If necessary the application can abort aprint in progress with the abort_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 torun the underlying exe files directly from the command line or a script, Please be awarethat future changes to these components may affect the ability to execute them from thecommand line.

In this mode of use, the dialogs are launched directly and given command-lineparameters. The command line options are the same as used by the LSPrintAPI library.The launch_print_options_dialog function corresponds to LSPrintDialog.exe, andlaunch_printing_dialog function corresponds to LSPrintingDialog.exe. For example:

LSPrintingDialog.exe --filename "C:/TestImage.bmp" --name "ASUS DRW-1612BLT 0.38 132 (F:)" --index 0 --quality best --path F --copies 1 --media 1 --deleteImageFile 1



1.3 Print Options Dialog DetailsThe “Print Options” dialog is what the user traditionally sees when “Print” is selected inthe labeling application. Below is a screenshot of the LightScribe Print Options dialogcomponent.

1.3.1 Major Features of Print Options Dialog

The drive enumeration and status and print preview operations are performed inseparate threads, resulting in up-to-date information and a UI that is responsiveduring these time-consuming activities.

LightScribe media is available in multiple colors; the print preview can begenerated in the available colors to give a realistic impression of how the labeleddisc 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 thecontrast 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 itwill take to print the image. This time is computed using information about thedrive’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.



1.4 Printing Dialog DetailsThe “Printing” or “Burn Progress” dialog is what the user traditionally sees duringprinting. Below is a screenshot of the LightScribe Printing dialog component.

1.4.1 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 LocalizationThe LightScribe Printing Components are localized into these languages:



Primary Language 3-LALangID(dec)

Arabic ARA 1025

Chinese Simplified CHS 2052

Chinese Traditional CHT 1028

Czech CSY 1029

Danish DAN 1030Dutch NLD 1043

Finnish FIN 1035French FRA 1036

German DEU 1031Greek ELL 1032

Hebrew HEB 1037Italian ITA 1040

Japanese JPN 1041Korean KOR 1042

Norwegian NOR 1044Polish PLK 1045

Portuguese PTB 1046Portuguese PTG 2070

Russian RUS 1049Slovak SKY 1051

Spanish ESN 1034Swedish SVE 1053

Turkish TRK 1055



The components are Microsoft Multilingual User Interface (MUI) enabled, so they willdetect which display language to use. Because of this, if the OS is running in onelanguage, but the user has set the Display Language to another language, the componentsmay be running in a different language than the application if the application is not MUIenabled and thus is not reading the Display Language.

1.6 Help SystemThe application’s help content is not required to include detailed help relating to theLightScribe printing functionality, but a basic walkthrough on printing a LightScribe discis recommended. Detailed help files on the Print Options and Printing Dialogs are HTMLfiles located in %CommonProgramFiles%\LightScribe\Content\help\<Language TLA>,and the user can view these by clicking the “Help” button on the printing components.



2 Library Usage

2.1 Library FootprintThe 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 LoadingApplications can use either build-time or run-time linking.

To use build-time (or implicit) linking, add the LSPrintAPI.lib import library toyour project linker settings and “#include “LSPrintAPI.h” to your code. In orderfor this to work, the dll needs to be in the search path for loading dlls. Thisrequires extra effort to read the location from the registry and add it to the path, soit is not the recommended approach.

To use run-time (or explicit) linking, the library needs to be loaded with theWindows API LoadLibrary. Additionally, the functions may need to be resolvedwith the Windows API GetProcAddress passing in the function’s name. This isthe method used in the sample application. It also uses the /DELAYLOAD linkeroption to prevent Windows from trying to load the LSPrintAPI library uponstartup of the application. When using this method, errors such as “Library NotFound” can be handled gracefully at runtime. Also, the library can be loaded onlywhen needed and unloaded when not needed.

This is demonstrated in the ImageBurner2 sample code functionLSSDKHelper::LS_LoadLibrary. Note that the sample code is not production-readycode.

2.3 Library DetectionAt runtime startup, applications should check (stat) for the presence of the LSPrintAPIlibrary. The absolute path and name of this dll is stored in the registry keyHKLM\SOFTWARE\LightScribe\LSPrintAPI. This key should be read and theapplication should check for the existence of the filename it provides.

This is demonstrated in the ImageBurner2 sample code functionLSSDKHelper::LS_GetLibraryLocation. Note that the sample code is not production-ready code.

If this key is not present or the location it specifies cannot be loaded, a localized messageshould be display to inform the user that they need to install the latest version of the



LightScribe System Software with a button or link to“http://www.lightscribe.com/go/downloads”.

2.4 Library Versioning StrategyFor most Windows API functions, only the names are preserved across differentWindows releases; the ordinals are subject to change. So, one cannot reliably importWindows API functions by their ordinals. Likewise, in this API, only the function namesare guaranteed to be preserved across releases. Because of this, linking/resolving shouldbe done using the function names rather than the ordinals. This will ensure backwardcompatibility of the library.NOTE: Applications should never install their own version of LSPrintAPI.dll (i.e. in theapplication’s folder); instead they must use the version that is part of the LightScribeSystem Software using the Library Detection technique described above.

2.5 LightScribe Software Update MechanismLightScribe technology is continually undergoing improvements and extensions, and it isimportant that the software on the user’s system remains up-to-date. The updating of theLightScribe Software is normally handled by the LightScribe Print Options component.The application will only prompt for an update when one of the functions returns anerror, or a problem occurs when loading the library. In this case, the application shoulddirect the user to “http://www.lightscribe.com/go/downloads”.

2.6 Application Installation RequirementsThe application installer should check for a version 1.10.19.1 or greater LightScribeSystem Software at install time. The full LightScribe System Software version number isstored in the registry key HKLM/Software/LightScribe/Update/CurrentVersion witha REG_SZ value.

2.7 Sample codeThe SDK includes two sample applications, ImageBurner2 and AutoPrint. ImageBurner2illustrates using the API for the standard usage scenario (See Section 1.2). The AutoPrintsample application illustrates using the API for the programmatic usage scenario. Theseare not production quality code, but they show the basic function calls required to use thelibrary for the two scenarios.

The ImageBurner2 sample application code can be built using the ImageBurner2 VisualStudio 2005 project (ImageBurner2SDK.vcproj). The AutoPrint sample application codecan be built using the AutoPrint Visual Studio project (AutoPrintSDK.vcproj). Alsoincluded 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 theSDK, the developer must have the LightScribe System Software installed in order to testthe application.



3 LSPrintAPI Library

3.1 API DefinitionBelow is an excerpt from LSPrintAPI.h showing the API. The remainder of this sectiondescribes each API in detail.

/**************************************************************************************//** API entry point for launching the Print Options dialog.* @param 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* @return 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.* @param 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* @return 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 ofvalid drives */const int LS_INVALID_ARRAY_SIZE = 3; /* Array size specified is too small for returnvalue */



/**************************************************************************************//** API entry point for testing if there is a LightScribe drive on the system.* Note: This requires the LightScribe System Software to be installed.* @param rHaveDrive Output parameter: true = 1 or false = 0* @return 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.* @param rDriveCount Output parameter: Number of drives* @return 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.* @param driveIndex Index of drive. Drives are numbered from 0 to driveCount - 1.* @param pDrivePath Output parameter: Name of the drive path* @param drivePathSize Allocated size of the drive path array.* @return 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.* @param driveIndex Index of drive. Drives are numbered from 0 to driveCount - 1.* @param pDriveDisplayName Output parameter: Display name of the drive* @param driveDisplayNameSize The length, in number of characters, already allocated to

pDriveDisplayName* @return 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.* @param driveIndex index of drive. Drives are numbered from 0 to driveCount - 1.* @param rDriveStatus Output parameter: Current status of the drive.* @return 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.* @param driveIndex Index of drive. Drives are numbered from 0 to driveCount - 1.* @param rPrintStatusCode Output parameter: Print status code.* @param rCurrentCopyNo Output parameter: Number of the current copy being printed.* @param rTotalNoOfCopies Output parameter: Total number of copies to print.* @param rPercentComplete Output parameter: Percentage of the print job completed on

the given drive.* @param rEstimatedTimeRemainingSecs Output parameter: Estimated time remaining in

seconds.* @param pPrintStatusString Output parameter: Print status string.* @param printStatusStringSize: Allocated size of the print status array.



* @param pEstimatedTimeRemainingString Output parameter: Estimated time remainingstring.* @param estimatedTimeRemainingStringSize: Allocated size of the estimated time

remaining array.* @return 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, unsignedint& 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.* @param driveIndex index of drive. Drives are numbered from 0 to driveCount - 1.* @return code: LS_SUCCESS or other error codes as per LSPrintAPI.h

**/LSPRINTAPI_EXPORT int abort_print(const unsigned int driveIndex);/**************************************************************************************/



3.2 launch_print_options_dialog

Definition:

int launch_print_options_dialog(const wchar_t* pOptions);

Input Parameter(s):

The pOptions argument is a C string with classic command line style parameters. Eachoption has a long version and a short version. The long versions are preceded with adouble dash, “--", and the short versions by a single dash, “-“. Some options require avalue, while others have no associated value but are parsed for their presence or non-presence only.

version – Using this (optional) option will display a dialog with the version number of thecomponent. 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 parametersdescribed. 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-offownership of the source image file. This is useful for the case where a temporary bmp filewas 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 preventneedlessly wasting storage space with the temporary file.When using "-d 0" it is important that the application does not delete the file fromunderneath the printing component. Hence, the recommended approach is for theapplication to use "-d 1" as a command line argument. This will transfer ownership of thefile to the printing component, which will delete it when it is finished. In combinationwith “-d 1”, it is recommended that the bitmap file passed in be a uniquely named filestored in the user’s temp folder (usually C:\Documents and Settings\<username>\Local Settings\Temp). This is demonstrated in the ImageBurner2 sample codefunction 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 imagethat 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



Return Codes:

The return codes for this API are the standard Windows error codes defined in thePlatform SDK file “winerror.h”. Therefore a return code of 0 (ERROR_SUCCESS) isreturned upon a successful function execution.

3.3 launch_printing_dialog

Definition:

int launch_printing_dialog(const wchar_t* pOptions);

Input Parameter(s):

The pOptions argument is a C string with classic command line style parameters. Eachoption has a long version and a short version. The long versions are preceded with andouble dash, “--", and the short versions by a single dash, “-“. Some options require avalue, while others have no associated value but are parsed for their presence or non-presence only.

version – Using this (optional) option will display a dialog with the version number of thecomponent. 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 parametersdescribed. 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-offownership of the source image file. This is useful for the case where a temporary bmp filewas 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 preventneedlessly wasting storage space with the temporary file.When using "-d 0" it is important that the application does not delete the file fromunderneath the printing component. Hence, the recommended approach is for theapplication to use "-d 1" as a command line argument. This will transfer ownership of thefile to the printing component, which will delete it when it is finished. In combinationwith “-d 1”, it is recommended that the bitmap file passed in should be a uniquelynamed file stored in the user’s temp folder (usually C:\Documents and Settings\<username>\Local Settings\Temp). This is demonstrated in the ImageBurner2 sample codefunction -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 imagethat is to be labeled. It should be a full path to the source bitmap. It is recommended thatthe 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). Thiswould be used in combination with the deleteImageFile parameter. We also recommendthat 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-basedlogical LightScribe drive number. The numbers are assigned in alphabetical order of thedrive 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 displaystring 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”. Otherpossible values are “normal” and “draft”.

path – This (required) parameter specifies the path of the selected logical LightScribedrive. On Windows should be a drive letter better ‘A’ to ‘Z’. The drive path must matchthe actual path of the selected logical LightScribe drive. i.e. if there are 3 LightScribeenabled 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 “--index1 --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 theLightScribe 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 trayalready. If this value is 0, then the tray will be ejected and the user will be prompted toinsert media (even if there actually is LightScribe media loaded). If the value is 1, thesoftware 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 shallautomatically close without user interaction. The default value is 0.



noShow – This (optional) parameter specifies that the printing dialog shall operate in thebackground (minimized). Any pop-up dialogs will be presented unless suppressed withthe noOperator option. The default value is 0.

autoEject – This (optional) parameter specifies that the tray should be opened when theprint 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 beused if optimal printing values are not supported. If optimal printing values are notsupported for the target drive the printing dialog will, by default, prompt the user tochoose to use either generic printing or update the system software. This parameter canbe used to prevent the prompt and inform the printing dialog to use generic printingvalues in this situation. Printing will continue without prompting the user. The defaultvalue is false (“0”).

noOperator – This (optional) parameter indicates there is no operator present to respondto GUI dialogs. All pop-up dialogs will be suppressed. If an error occurs that wouldnormally cause a dialog to be presented, the print will terminate and an error code will bereturned. The default value is false (“0”).


None

Return Codes:

The return codes for this API are the standard Windows error codes defined in thePlatform SDK file “winerror.h”. Therefore a return code of 0 (ERROR_SUCCESS) isreturned upon a successful function execution.

3.4 have_lightscribe_drive

Definition:

int have_lightscribe_drive(bool &rHaveDrive);

Input Parameter(s):

None




rHaveDrive – This parameter returns the value true if there is a LightScribe drive on thesystem 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


rDriveCount – The number of LightScribe drives in the system. The LightScribe drivesare numbered from 0 to driveCount -1.

Return Codes:


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 numberedfrom 0 to driveCount – 1.

drivePathSize – The length, in number of characters, already allocated to pDrivePath.




pDrivePath – The path name of the LightScribe drive with the given index number. Thepath name is assigned by the operating system.

Return Codes:


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):


displayNameSize – The length, in number of characters, already allocated topDriveDisplayName.


pDriveDisplayName – The display name of the LightScribe drive with the given indexnumber.

Return Codes:


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)



Input Parameter(s):



rDriveStatus – One of the LSDriveStatus enumerated values.

Return Codes:


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):


printStatusStringSize - The length, in number of characters, already allocated torPrintStatusString.

estimatedTimeRemainingStringSize - The length, in number of characters, alreadyallocated to rEstimatedTimeRemaining.




rPrintStatusCode – One of the enumerated values from LSPrintStatusCode.h. Thisdescribes 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 theprint completes.

pPrintStatusString – A displayable string indicating the current status of the print.

pEstimatedTimeRemainingString – A displayable string indicating the estimated timeremaining in minutes until the print completes.

Return Codes:


3.10 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 theprint 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):



None.



Return Codes:


LightScribe Public Windows SDK Documentation

Documents

Transcript of LightScribe Public Windows SDK Documentation