Lightscribe Public Windows Software Development Kit
←
→
Page content transcription
If your browser does not render page correctly, please read the page content below
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 23LightScribe Public Windows Software Development Kit (SDK)
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
Document Number: PWSDK Revision: 3, Date:12/10/2008
Page 3 of 23LightScribe Public Windows Software Development Kit (SDK)
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.
Document Number: PWSDK Revision: 3, Date:12/10/2008
Page 4 of 23LightScribe Public Windows Software Development Kit (SDK)
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
Document Number: PWSDK Revision: 3, Date:12/10/2008
Page 5 of 23LightScribe Public Windows Software Development Kit (SDK)
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.
Document Number: PWSDK Revision: 3, Date:12/10/2008
Page 6 of 23LightScribe Public Windows Software Development Kit (SDK)
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:
Document Number: PWSDK Revision: 3, Date:12/10/2008
Page 7 of 23LightScribe Public Windows Software Development Kit (SDK)
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
Document Number: PWSDK Revision: 3, Date:12/10/2008
Page 8 of 23LightScribe Public Windows Software Development Kit (SDK)
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\,
and the user can view these by clicking the “Help” button on the printing components.
Document Number: PWSDK Revision: 3, Date:12/10/2008
Page 9 of 23LightScribe Public Windows Software Development Kit (SDK)
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
Document Number: PWSDK Revision: 3, Date:12/10/2008
Page 10 of 23LightScribe Public Windows Software Development Kit (SDK)
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.
Document Number: PWSDK Revision: 3, Date:12/10/2008
Page 11 of 23LightScribe Public Windows Software Development Kit (SDK)
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 */
Document Number: PWSDK Revision: 3, Date:12/10/2008
Page 12 of 23LightScribe Public Windows Software Development Kit (SDK)
/**************************************************************************************/
/** 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.
Document Number: PWSDK Revision: 3, Date:12/10/2008
Page 13 of 23LightScribe Public Windows Software Development Kit (SDK)
* @param pEstimatedTimeRemainingString Output parameter: Estimated time remaining
string.
* @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, 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.
* @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);
/**************************************************************************************/
Document Number: PWSDK Revision: 3, Date:12/10/2008
Page 14 of 23LightScribe Public Windows Software Development Kit (SDK)
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.
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\\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
Document Number: PWSDK Revision: 3, Date:12/10/2008
Page 15 of 23LightScribe Public Windows Software Development Kit (SDK)
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.
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\\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
Document Number: PWSDK Revision: 3, Date:12/10/2008
Page 16 of 23LightScribe Public Windows Software Development Kit (SDK)
folder (usually C:\Documents and Settings\\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.
Document Number: PWSDK Revision: 3, Date:12/10/2008
Page 17 of 23LightScribe Public Windows Software Development Kit (SDK)
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
Document Number: PWSDK Revision: 3, Date:12/10/2008
Page 18 of 23LightScribe Public Windows Software Development Kit (SDK)
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.
Document Number: PWSDK Revision: 3, Date:12/10/2008
Page 19 of 23LightScribe Public Windows Software Development Kit (SDK)
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)
Document Number: PWSDK Revision: 3, Date:12/10/2008
Page 20 of 23LightScribe Public Windows Software Development Kit (SDK)
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.
Document Number: PWSDK Revision: 3, Date:12/10/2008
Page 21 of 23LightScribe Public Windows Software Development Kit (SDK)
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.
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):
driveIndex – The index number of a LightScribe drive. LightScribe drives are numbered
from 0 to driveCount – 1.
Output Parameter(s):
None.
Document Number: PWSDK Revision: 3, Date:12/10/2008
Page 22 of 23LightScribe Public Windows Software Development Kit (SDK)
Return Codes:
This function returns a LightScribe Error Code as described in LSPrintAPI.h. On success,
the function returns LS_SUCCESS.
Document Number: PWSDK Revision: 3, Date:12/10/2008
Page 23 of 23You can also read
