LightScribe Public Windows SDK Documentation

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
(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.
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 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()
LightScribe Public Windows Software Development Kit (SDK)
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.
Document Number: PWSDK Revision: 3, Date:12/10/2008

Page 2 of 23
Contents
Lightscribe Public Windows Software Development Kit................................................... 1

1 Introduction................................................................................................................. 4
1.1 Architecture and Usage of LightScribe Printing Components............................. 4
1.2 API Usage Scenarios............................................................................................ 4
1.3 Print Options Dialog Details ................................................................................ 6
1.3.1 Major Features of Print Options Dialog........................................................ 6
1.4 Printing Dialog Details......................................................................................... 7
1.4.1 Major Features of Printing Dialog ................................................................ 7
1.5 Localization.......................................................................................................... 7
1.6 Help System ......................................................................................................... 9
2 Library Usage............................................................................................................ 10
2.1 Library Footprint ................................................................................................ 10
2.2 Linking/Library Loading.................................................................................... 10
2.3 Library Detection ............................................................................................... 10
2.4 Library Versioning Strategy............................................................................... 11
2.5 LightScribe Software Update Mechanism ......................................................... 11
2.6 Application Installation Requirements............................................................... 11
2.7 Sample code ....................................................................................................... 11
3 LSPrintAPI Library................................................................................................... 12
3.1 API Definition .................................................................................................... 12
3.2 launch_print_options_dialog.............................................................................. 15
3.3 launch_printing_dialog....................................................................................... 16
3.4 have_lightscribe_drive ....................................................................................... 18
3.5 get_drive_count.................................................................................................. 19
3.6 get_drive_path.................................................................................................... 19
3.7 get_drive_display_name..................................................................................... 20
3.8 get_drive_status.................................................................................................. 20
3.9 get_print_status .................................................................................................. 21
3.10 abort_print ...................................................................................................... 22

Page 3 of 23
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 2nd and 3rd pieces of functionality. The actual
components are distributed as part of the LightScribe System Software Version 1.10.19.1
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
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 the get_print_status() API. If necessary the application can abort a
print 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 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.
The launch_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 0.38 132 (F:)" --index 0 --quality best --path F --copies 1 --
media 1 --deleteImageFile 1

Page 5 of 23
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.
1.3.1 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
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.
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 Localization
The LightScribe Printing Components are localized into these languages:

Page 7 of 23
LangID
Primary Language 3-LA (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
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
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 production-
ready 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
LightScribe System Software with a button or link to

“http://www.lightscribe.com/go/downloads”.
2.4 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 “http://www.lightscribe.com/go/downloads”.
2.6 Application Installation Requirements

The application installer should check for a version 1.10.19.1 or greater LightScribe
System Software at install time. The full LightScribe System Software version number is
stored in the registry key HKLM/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
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.
* @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 of
valid drives */
const int LS_INVALID_ARRAY_SIZE = 3; /* Array size specified is too small for return
value */

Page 12 of 23
/**************************************************************************************/
/** 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.
* @param rDriveCount Output parameter: Number of drives
**/
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"...
* @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.
**/
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.
* @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.
* @param driveIndex index of drive. Drives are numbered from 0 to driveCount - 1.
* @param rDriveStatus Output parameter: Current status of the drive.
**/
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.
* @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.

Page 13 of 23
* @param pEstimatedTimeRemainingString Output parameter: Estimated time remaining

string.
* @param estimatedTimeRemainingStringSize: Allocated size of the estimated time
remaining array.
**/
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: 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.
**/
LSPRINTAPI_EXPORT int abort_print(const unsigned int driveIndex);
/**************************************************************************************/

Page 14 of 23
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. 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 non-
presence 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.
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
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):
The pOptions 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 non-
presence 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.
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.
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().
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
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_”.
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.
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.
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.
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).
autoClose – This (optional) parameter specifies that the printing dialog shall
automatically close without user interaction. The default value is 0.

Page 17 of 23
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”).
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
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
rDriveCount – The number of LightScribe drives in the system. The LightScribe drives
are 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 numbered
from 0 to driveCount – 1.
drivePathSize – The length, in number of characters, already allocated to pDrivePath.

Page 19 of 23
pDrivePath – The path name of the LightScribe drive with the given index number. The
path 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 to

pDriveDisplayName.
pDriveDisplayName – The display name of the LightScribe drive with the given index
number.
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)

Page 20 of 23
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 to

rPrintStatusString.
estimatedTimeRemainingStringSize - The length, in number of characters, already

allocated to rEstimatedTimeRemaining.

Page 21 of 23
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:
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 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):
None.

Page 22 of 23
Return Codes:

Page 23 of 23

LightScribe Public Windows SDK Documentation

Hochgeladen von

Dokumentinformationen

Originalbeschreibung:

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

LightScribe Public Windows SDK Documentation

Hochgeladen von

Copyright:

Verfügbare Formate

Lightscribe Public Windows Software Development Kit

About this Specification

Legal Disclaimers and Licensing Claims

Version 2.0, February 6, 2008

Version 1.0, January 3, 2008

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

Lightscribe Public Windows Software Development Kit................................................... 1

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

 Provide a short learning curve on the LightScribe interfaces with no need to

In a disc labeling application, three main pieces of functionality exist:

1. The Label Designer

1.1 Architecture and Usage of LightScribe Printing Components

1.2 API Usage Scenarios

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

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

Command Line Usage:

LSPrintingDialog.exe --filename "C:/TestImage.bmp" --name "ASUS DRW-

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

1.3 Print Options Dialog Details

1.3.1 Major Features of Print Options Dialog

1.4 Printing Dialog Details

1.4.1 Major Features of Printing Dialog

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

Arabic ARA 1025

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

1.6 Help System

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

2.2 Linking/Library Loading

This is demonstrated in the ImageBurner2 sample code function

2.3 Library Detection

This is demonstrated in the ImageBurner2 sample code function

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

LightScribe System Software with a button or link to

2.4 Library Versioning Strategy

2.5 LightScribe Software Update Mechanism

2.6 Application Installation Requirements

2.7 Sample code

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

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

* @param pEstimatedTimeRemainingString Output parameter: Estimated time remaining

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

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

folder (usually C:\Documents and Settings\<user name>\Local Settings\Temp). This

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

noOperator – This (optional) parameter indicates there is no operator present to respond

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

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

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

displayNameSize – The length, in number of characters, already allocated to

int get_drive_status(const unsigned int driveIndex, LSDriveStatus&

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

int get_print_status(const unsigned int driveIndex,

printStatusStringSize - The length, in number of characters, already allocated to

estimatedTimeRemainingStringSize - The length, in number of characters, already

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

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

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

pEstimatedTimeRemainingString – A displayable string indicating the estimated time

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

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