Professional Documents
Culture Documents
Devmode API /
PRINTERINFO Manual
Overview
Outline of Devmode API and PRINTERINFO.
PRINTERINFO
About PRINTERINFO.
M00003704
Rev.E
Cautions
No part of this document may be reproduced, stored in a retrieval system, or transmitted in any form or
by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written
permission of Seiko Epson Corporation.
The contents of this document are subject to change without notice. Please contact us for the latest
information.
While every precaution has taken in the preparation of this document, Seiko Epson Corporation assumes
no responsibility for errors or omissions.
Neither is any liability assumed for damages resulting from the use of the information contained herein.
Neither Seiko Epson Corporation nor its affiliates shall be liable to the purchaser of this product or third
parties for damages, losses, costs, or expenses incurred by the purchaser or third parties as a result of:
accident, misuse, or abuse of this product or unauthorized modifications, repairs, or alterations to this
product, or (excluding the U.S.) failure to strictly comply with Seiko Epson Corporations operating and
maintenance instructions.
Seiko Epson Corporation shall not be liable against any damages or problems arising from the use of any
options or any consumable products other than those designated as Original EPSON Products or EPSON
Approved Products by Seiko Epson Corporation.
Trademarks
EPSON and ESC/POS are registered trademarks of Seiko Epson Corporation in the U.S. and other countries.
MS-DOS, Microsoft, Win32, Windows, Windows Vista, Windows Server, Visual Studio, Visual Basic,
Visual C++, and Visual C# are either registered trademarks or trademarks of Microsoft Corporation in the
United States and other countries.
For Safety
Key to Symbols
Thesymbolsinthismanualareidentifiedbytheirlevelofimportance,asdefinedbelow.Readthe
followingcarefullybeforehandlingtheproduct.
Provides information that must be observed to avoid damage to your equipment or a
malfunction.
Provides important information and useful tips.
Restriction of Use
Whenthisproductisusedforapplicationsrequiringhighreliability/safetysuchastransportation
devicesrelatedtoaviation,rail,marine,automotiveetc.;disasterpreventiondevices;varioussafety
devicesetc;orfunctional/precisiondevicesetc,youshouldusethisproductonlyaftergiving
considerationtoincludingfailsafesandredundanciesintoyourdesigntomaintainsafetyandtotal
systemreliability.Becausethisproductwasnotintendedforuseinapplicationsrequiringextremely
highreliability/safetysuchasaerospaceequipment,maincommunicationequipment,nuclearpower
controlequipment,ormedicalequipmentrelatedtodirectmedicalcareetc,pleasemakeyourown
judgmentonthisproductssuitabilityafterafullevaluation.
Manual Content
Themanualismadeupofthefollowingsections:
Chapter 1
Overview
Chapter 2
Chapter 3
Chapter 4
Chapter 5
PRINTERINFO
Contents
For Safety...............................................................................................................................3
Key to Symbols ....................................................................................................................................... 3
Contents ................................................................................................................................5
Overview ........................................................................................7
Contents of This Manual ....................................................................................................................... 7
Provided File..........................................................................................................................8
Sample Program .................................................................................................................................... 8
Operational Environment.....................................................................................................9
OS ............................................................................................................................................................ 9
.NET Framework Version ........................................................................................................................ 9
APDDM_Close..................................................................................................................... 20
Command ID ...................................................................................................................... 21
APD_DM_PAPER_SIZE ............................................................................................................................21
APD_DM_ORIENTATION........................................................................................................................21
APD_DM_PAPERSAVE ...........................................................................................................................21
APD_DM_INPUT_UNIT ............................................................................................................................21
APD_DM_PAPER_BIN.............................................................................................................................22
APD_DM_SPEED_DEVICE......................................................................................................................22
APD_DM_REPLACEFONT ......................................................................................................................22
PRINTERINFO .................................................................................27
Acquiring TM Printer Status Using PRINTERINFO_2 ........................................................... 27
Chapter 1 Overview
Overview
ThismanualdescribesDevmodeAPIandPrinterInfo.
DevmodeAPIforAPDprovidesafunctiontoacquire/setupdeviceuniqueDevmodefrom
usersapplication.ParametersandsettingrangeofcommandIDs(functionsofDevmodeAPI)
areacquiredfromthedevice,andtheparameterissettothedevicebytheapplication.
PRINTERINFOisoneofWindowsstructures.InadditiontoStatusAPIprovidedbyEPSONto
acquireTMprinterstatusbytheuserapplication,Windowsfunctionscanbeusedforthat
purpose.ForPRINTERINFOinformation,refertoAcquiringTMPrinterStatusUsing
PRINTERINFO_2onpage27.Fordetails,refertotheMicrosoftwebsite.
Install manual
DescriptionsoftheproceduresfrominstallingtheAPDtoperformingtestprint,adding
printerdrivers,changingport,andthesilentinstallationthatisanautomatedAPD
installation.
TM Printer Manual
DescriptionsofhowtousetheAPDanditsfunctions.
DescriptionsofthespecificationsofTMT81.
Provided File
EPSONprovidesthefollowingfiles:
Type
File Name
Description
In this file, API is defined during creation of Win32 32bit application.
APDDM_API.H
EAPDM32.DLL
EAPDM32W.DLL
Sample Program
DevmodeAPIisusedforChangingpaperfeedingmodeinthesampleprogram.
Chapter 1 Overview
Operational Environment
OS
ConformingtotheAPDenvironment.RefertoInstallManual.
OnWindowsXP,no.NETmodulesareinstalledwithout.NETFramework2.0duringAPD
installation.If.NETFramework2.0wasinstalledlater,installDevmodeAPI.NETusingcustom
installationofAPD.
In Terminal Service / Citrix XenApp environment, the status of TM printers cannot be
acquired using PRINTER_INFO_2.
10
Sequence
RecommendedsequenceforWin32isasshownbelow.
.NET
Framework
User
.NET Application
EPDA32W.DLL
1:Load Library()
2:GetProcAddress()
3:APDDM_OpenW(SYSTEM/Default/Input)
4:APDDM_GetRange()
7:APDDM_SetData()
8:APDDM_GetDevModeW(lpParam=NULL)
9:return APDDM_GetDevModeW()
Allocate the memory
size required for
DEVMODEW.
10:APDDM_Close()
11:FreeLibrary()
12:CreateDCW(DEVMODEW)
Deletes DEVMODEW
memory.
13:Printing Functions()
11
Explanation
1
2
3
4
5
6
7
8
9
12
LoadLibrary()
GetProcAddress()
APDDM_OpenW(SYSTEM/Default/Input)
Opens Devmode API. When using Devmode API of the device, use
System Devmode to open.
APDDM_GetRange()
Specifies a command ID and acquires the setting range that can be set
for the ID from the device.
Provides the acquired command ID range to the user.
The user makes selection from the range.
APDDM_SetData()
Sets a value to the device.
APDDM_GetDevModeW()
Acquires the set value of the device. It is recommended that the
application acquire/store this value.
return APDDM_GetDevModeW()
Acquires the memory size required for DEVMODEW. The application
allocates memory.
10
APDDM_Close()
Closes Devmode API.
11
FreeLibrary()
Deletes the memory allocated by Devmode API.
12
CreateDCW(DEVMODEW)
Deletes DEVMODEW memory.
13
Printing Functions()
Printing with the set contents is available.
Recommendedsequencefor.NETisasshownbelow.
.NET
Framework
User
.NET Application
EPDA32W.DLL
1:p=new APDDM()
2:p.OpenW(SYSTEM/Default/Input)
3:p.GetRange()
6:p.SetData()
7:p.GetDevModeW(lpParam=NULL)
8:return p.GetDevmodew()
Allocate the memory
size required for
DEVMODEW.
10:PrinterSettings m.GetHdevmode()(DEVMODEW)
11:Printing Functions()
9:p.Close()
Deletes the memory
allocated by
Devmode API.
13
Character Code
Unicodeisusedforallstrings.
Unicodeisusedforallstrings.ItisrequiredtosetUNI_CODEand_UNICODEinthecompiler
macrodefinition.UseWidecharacterforallWindowsAPIs.
Devmode Type
ThefollowingthreeDevmodetypesareavailablewhenopened:
SystemDEVMODE
DEVMODEsetintheprinterdriverisusedastheinputparameter.Inthiscase,setNULL
becauseDEVMODEWaddressisnotusedforinput.
DefaultDEVMODE
ThedefaultDEVMODEfortheprinterdriverisusedastheinputparameter.Inthiscase,set
NULLbecauseDEVMODEWaddressisnotusedforinput.
SpecifiedDEVMODE
DEVMODEacquiredindependentlybytheapplicationisusedastheinputparameter.
CanbeacquiredfromDocumentPropertySheetandWindowsAPI.
TheDEVMODEWareathatisallocatedbytheapplicationneedstobereleasedbythe
application.
Memory Allocation
TheDevmodeAPImoduledoesnotneedtoreleasethememoryareathatreturnsasaparameter.
FreeLibrary()oftheDevmodeAPImodulereleasesthememoryarea.Thatiswhyyoushould
copythememoryareainadvancewhenthedataneedstobestored.
DEVMODEWacquiredbyGetDevmodeW(.NET)orAPDDM_GetDevModeW(Win32)isusedin
alaterprintingprocessandisnotreleasedbytheDevmodeAPImodule.So,releaseitbythe
application.
14
Multi-process/Multi-thread/Multi-user
BecausetheDevmodeAPIcanhandletheinstancesofDEVMODEWatthesametime,it
supportsmultiprocess/multithread/multiuser.
Forapplications,.NETversioncandistinguishtheinstanceswiththeobject,andWin32version
candistinguishtheinstanceswiththeprinterdeviceinformationhandle.TheDevmodeAPI
moduledoesnotneedtoreleasethememoryareathatreturnsasaparameter.
Error Code
TheerrorcodesreturnedbyeachAPIareidenticaltotheWindowserrorcodes(definedin
WinError.h).
15
16
APDDM_OpenW
Opensthespecifiedprinterdeviceandenablesdeviceinformationacquisition/setting.
lphAPDDMforthespecifiedDEVMODE,itisrequiredtoallocateanddeletememorybythe
application.
Syntax
DWORD APDDM_OpenW ( LPCWSTR lpwDevName,
DWORD dwType, LPDEVMODEW lpDM,
LPHANDLE lphAPDDM)
Argument
lpwDevName:
Printerdevicenameaddress.ThisisLPCWSTRtype.
dwType:
DEVMODEtypewhenopened.Selectamongthefollowing:
SystemDEVMODE/DefaultDEVMODE/SpecifiedDEVMODE.
ThisisDWORDtype.
lpDM:
DEVMODEWaddress.ThisisLPDEVMODEWtype.
lphAPDDM:
Printerdeviceinformationhandleaddress.ThisisLPHANDLEtype.
17
APDDM_GetRange
AcquiresthesettingrangeofthespecifiedcommandIDfromthedevice.
Syntax
DWORD APDDM_GetRange ( HANDLE hAPDDM,
DWORD nCommad,
LPVOID* lpParam,
LPDWORD pdwCount,
LPDWORD pdwSize)
Argument
hAPDDM:
Printerdeviceinformationhandle.ThisisHandle.
nCommad
CommandID(function)toacquiretheexecutionlevel.
ThisisDWORDtype.
lpParam:
Thesettingrangestorageparameter.ThisisLPVOID*type.
pdwCount:
Thenumberofelements.ThisisLPDWORDtype.
pdwSize:
Theparametersize.Thenumberofparametersdividedbythenumber
ofelementsindicatesthenumberofarraysofParam.
ThisisLPDWORDtype.
APDDM_GetData
AcquiresthedataofthespecifiedcommandIDfromthedevice.
Syntax
DWORD APDDM_GetData ( HANDLE hAPDDM,
DWORD nCommad,
LPVOID* lpParam, LPDWORD pdwSize)
Argument
18
hAPDDM:
Printerdeviceinformationhandle.ThisisHandle.
nCommad
CommandID(function)toacquiretheexecutionlevel.
ThisisDWORDtype.
lpParam:
Obtaineddatastorageparameter.ThisisLPVOID*type.
pdwSize:
Obtaineddatasize.ThisisLPDWORDtype.
APDDM_SetData
Configuresthespecifieddatatothedevice.
Syntax
DWORD APDDM_SetData ( HANDLE hAPDDM, DWORD nCommad,
LPVOID lpParam, LPDWORD pdwSize)
Argument
hAPDDM:
Printerdeviceinformationhandle.ThisisHandle.
nCommad
CommandID(function)toconfigurethedata.ThisisDWORDtype.
lpParam:
Configureddatastorageparameter.ThisisLPVOIDtype.
pdwSize:
Configureddatasize.ThisisLPDWORDtype.
APDDM_GetDevModeW
AcquiresDEVMODEinformation,towhichtheprinterdeviceinformationisapplied,tothe
specifiedarea.ForlpDMoftheobtainedDEVMODE,itisrequiredtoallocateanddelete
memorybytheapplication.
Syntax
DWORD APDDM_GetDevModeW ( HANDLE hAPDDM,
LPDEVMODE lpDM,
LPDWORD pdwSize)
Argument
hAPDDM:
Printerdeviceinformationhandle.ThisisHandle.
lpDM
DEVMODEaddress.ThisisLPDEVMODEtype.
pdwSize:
ObtainedDEVMODEWsize.ThisisLPDWORDtype.
19
APDDM_Close
Closesthespecifiedprinterdevice.
Syntax
DWORD APDDM_Close ( HANDLE hAPDDM)
Argument
hAPDDM:
20
Printerdeviceinformationhandle.ThisisHandle.
Command ID
APD_DM_PAPER_SIZE
Acquiresorchangesthepapersize.Userdefinedpapersarenotsupported.
Forpapersizenameacquisition,thefollowingtwomethodsareavailable:
Enumerationtype:Enumeratesthepapersizenames.Thepapersizenamescorrespondtothe
arrayofpapersizes.
ThecommandIDcanbespecifiedwiththefollowingmacro:
GET_ENUM_STRING_COMMAND_ID(COMMAND)
Singletype:Acquiresapapernamebyspecifyingasinglepapersize.
ThecommandIDcanbespecifiedwiththefollowingmacro:
GET_STRING_COMMAND_ID(COMMAND,ID)
APD_DM_ORIENTATION
Acquiresorchangestheprintdirection.Selecttheprintdirectionamongthefollowing:0degree,
90degree,180degree,and270degree.
Tochangethedirectiontoanyoptionotherthan0degree,itisrequiredtosetYestoPrintall
documentsasimageinformatting.
APD_DM_PAPERSAVE
Acquiresorchangesthemarginreductionsetting.Selectthesettingamongthefollowing:No
marginreduction/Uppermarginreduction/Bottommarginreduction/Upperandbottommargin
reduction.Availableoptionsdependontheprintermodel.
APD_DM_INPUT_UNIT
Acquiresorchangesthedriverinputunit.Specifyeithermmorinch.
21
APD_DM_PAPER_BIN
Acquiresorchangesthepaperfeeder.Availableoptionsdependontheprintermodel.
Foracquisitionofpaperfeedername,enumerationtypeandsingletypemacrosareavailableas
withchangingpapersize.
APD_DM_SPEED_DEVICE
Acquiresorchangestheprintspeed.Availableoptionsdependontheprintermodel.
APD_DM_REPLACEFONT
SpecifieswhetherornottosubstituteTrueTypefontstodevicefonts.Itisrequiredtoassign
TrueTypefontstodevicefontsmanuallyinadvance.
22
OpenW
CallsAPDDM_OpenWforWin32.
Opensthespecifiedprinterdeviceandenablesdeviceinformationacquisition/setting.
Theprinterinformationhandleretainedbythewrapper.
ToacquiretheDEVMODEstructurepointer,acquirethehandletotheDEVMODEstructurepointer
fromtheapplicationfirstandthenacquirethepointerusingGlobalLockwhichisanunmanaged
method.Afteruse,callGlobalUnLock,GlobalFreewhichareunmanagedmethods,andreleasethe
pointerbytheapplication.
Syntax
OpenW ( String strDevName, UInt32 un32Type, IntPtr npDM)
Argument
strDevName:
Printerdevicenamestring.ThisisStringtype.
un32Type
DEVMODEtypewhenopened.Selectamongthefollowing:System
DEVMODE/DefaultDEVMODE/SpecifiedDEVMODE.
ThisisUInt32type.
npDM:
DEVMODEstructurepointer.ThisisIntPtrtype.
23
GetRange
CallsAPDDM_GetRangeforWin32.
AcquiresthesettingrangeofthespecifiedcommandIDfromthedevice.
Syntax
GetRange ( UInt32 un32Commad, out IntPtr npParam,
out UInt32 un32Count, out UInt32 un32Size)
Argument
un32Commad
CommandID(function)toacquiretheexecutionlevel.ThisisUInt32
type.
npParam:
Thesettingrangestorageparameter.Contentsdifferdepending
onthecommandID.ThisisIntPtrtype.
un32Count:
Thenumberofelements.ThisisUInt32type.
un32Size
Theparametersize.Thenumberofparametersdividedbythenumber
ofelementsindicatesthenumberofarraysofParam.ThisisUInt32type.
GetData
CallsAPDDM_GetDataforWin32.
AcquiresthedataofthespecifiedcommandIDfromthedevice.
Syntax
GetData ( UInt32 un32Commad, out IntPtr npParam,
out UInt32 un32Size)
Argument
24
un32Commad
CommandID(function)toacquiretheexecutionlevel.
ThisisUInt32type.
npParam:
Obtaineddatastorageparameter.ThisisIntPtrtype.
un32Size:
Datasizeoftheobtainedparameter.ThisisUInt32type.
SetData
CallsAPDDM_SetDataforWin32.
Configuresthespecifieddatatothedevice.
Syntax
SetData ( UInt32 un32Commad, IntPtr npParam, UInt32 un32Size)
Argument
un32Commad
CommandID(function)toacquiretheexecutionlevel.
ThisisUInt32type.
npParam:
Configureddatastorageparameter.ThisisIntPtrtype.
un32Size:
Specifiestheparameterdatasize.ThisisUInt32type.
GetDevModeW
CallsAPDDM_GetDevModeWforWin32.
AcquiresDEVMODEinformation,towhichtheprinterdeviceinformationisapplied,tothe
specifiedarea.
ToacquiretheDEVMODEstructurepointer,acquirethehandletotheDEVMODEstructure
pointerfromtheapplicationfirstandthenacquirethepointerusingGlobalLockwhichisan
unmanagedmethod.Afteruse,callGlobalUnLock,GlobalFreewhichareunmanagedmethods,
andreleasethepointerbytheapplication.
Syntax
GetDevModeW ( IntPtr npDM, out UInt32 un32Size)
Argument
npDM
DEVMODEWstructurepointer.ThisisIntPtrtype.
un32Size
DEVMODEWstructuresize.ThisisUInt32type.
25
Close
CallsAPDDM_CloseforWin32.
Closesthespecifiedprinterdevice.
Syntax
Close ()
26
Chapter 5 PRINTERINFO
PRINTERINFO
Acquiring TM Printer Status Using PRINTERINFO_2
StatusAPIisprovidedforyourapplicationstoobtainthestatusoftheTMprinter.Thestatuscan
beobtainedalsousingWindowsfunctions.
ThestatusofPRINTER_INFO_2structurecanbeobtainedusingGetPrinterfunction.Fordetails,
refertoMicrosofthomepage.
In Terminal Service / Citrix XenApp environment, the status of TM printers cannot be
acquired using PRINTER_INFO_2.
ThestatusesofPRINTER_INFO_2structureandtheTMprinterareshownbelow.
PRINTERINFO_2 Status
TM Printer
PRINTER_STATUS_BUSY
Not supported.
PRINTER_STATUS_DOOR_OPEN
PRINTER_STATUS_ERROR
Not supported.
PRINTER_STATUS_INITIALIZING
PRINTER_STATUS_IO_ACTIVE
Not supported.
PRINTER_STATUS_MANUAL_FEED
PRINTER_STATUS_NO_TONER
PRINTER_STATUS_NOT_AVAILABLE
PRINTER_STATUS_OFFLINE
TM printer is off-line.
PRINTER_STATUS_OUT_OF_MEMORY
Not supported.
PRINTER_STATUS_OUTPUT_BIN_FULL
Not supported.
PRINTER_STATUS_PAGE_PUNT
Not supported.
PRINTER_STATUS_PAPER_JAM
Not supported.
PRINTER_STATUS_PAPER_OUT
No roll paper.
PRINTER_STATUS_PAPER_PROBLEM
Not supported.
PRINTER_STATUS_PAUSED
Not supported.
PRINTER_STATUS_PENDING_DELETION
Not supported.
PRINTER_STATUS_POWER_SAVE
Not supported.
PRINTER_STATUS_PRINTING
Printing.
PRINTER_STATUS_PROCESSING
Not supported.
PRINTER_STATUS_SERVER_UNKNOWN
Not supported.
PRINTER_STATUS_TONER_LOW
27
28