GUI ScreenIO for Windows

 ScreenIO.com


GetPrinters

The GetPrinters API returns a list of printers that are "visible" to the local machine.  For purposes of this discussion visible means that the local machine either has the printer installed locally, has the printer defined in its list of installed printers (Start / Settings Printers), which may include printers shared by other machines, OR - printers which the local machine can "see" if it browses the network neighborhood.

With our CopyFile API, you can copy files to these printers (even if you do not have printer drivers installed on the local machine).  

This API returns a table of up to 25 printer names, and associated information, attributes, and status conditions, etc., about each printer.  The level of detail and the specific information returned depends on the version of Windows, where the printer is attached, and whether or not drivers are installed for that printer.  Specifically, printers attached to other machines on the network (especially dissimilar machines such as Unix or Linux servers) may be visible but may not return any status information that is useable.  

In all cases enough information is returned to copy a file to the printer, subject to access rights.

You may select the level of detail desired, and also retrieve less than all the printers if desired.  You may also select to just retrieve information for the default printer, although this is not guaranteed to work under WinXP.  (Its best to retrieve all, then look in the table for the printer with the Default Attribute set.

Client/Server issues

If running in client/server mode, this API will list the printers visible on (or from) the client.

To list printers on the server set the following 88 to true:

     SET WIN32API-EXECUTE-API-ON-SERVER TO TRUE

Why Use This:

Many compilers have a facility to acquire the list of printers for a workstation by opening the Windows Printer Selection window.  However this will not work with the Client Server, as the window opens on the machine running the program (the Server) which may be several hundred miles from the Client.  By using this API to fetch printers, and displaying them in a simple combo-box, you can assure that your application will run in client server deployments.

Files

Files available to copy to your system:

Usage

     COPY WIN32API.
     COPY GETPRINTER.

     SET GP-GET-ALL-MY-PRINTERS TO TRUE                         
     SET GP-PRINT-MAX TO TRUE                                   
     SET GP-INFO-BASIC TO TRUE                                  
     MOVE LOW-VALUES TO GP-PRINTER-TABLE-AREA                   
 *                                                               
 * ------------------------: Call the GUI ScreenIO API routine:  
 *                                                               
     SET API-GETPRINTERS     TO TRUE                            
     CALL 'GSWINAPI' USING WIN32API-PARMS                       
                           GP-SERVER-HOST-NAME                  
                           GP-INFO-LEVEL                        
                           GP-PRINT-COUNT                       
                           GP-PRINTER-TABLE-AREA                
                           DUMMY                                
                           DUMMY                                

Parameters specific to this function

GP-SERVER-HOST-NAME

This is the machine from which you wish to obtain a list of printers.  Leaving it blank, or setting GET-ALL-MY-PRINTERS to TRUE will fetch the names of printers installed on the local machine.  (NOTE: Windows 9x machines also fetch network printers that are defined in their installed printer list).  Host names are of the form \\hostname.  Other esoteric possibilities for this field include forms documented in MSDN EnumPrinters documentation.

WARNING: 

When you ask for the printers on another machine by filling in something like \\MYSERVER  in the GP-SERVER-HOST-NAME field, it causes Windows to perform a BLOCKING Remote Procedure Call to that machine asking for a list of printers.  This can take a LONG time to return, and in certain cases can lock up your machine.  This is especially true in the case of large networks.  Windows XP seems to lock up more often than other versions.

Because of this you should be careful about allowing the application to search for printers on a specific host without WARNING the user that this could take a while.  If that machine is down, it could take much longer waiting for the function to time out.  

Also requesting GP-INFO-DETAILED (below) will return information more reliably than the other levels when accessing the printers of another machine on the network.  Often requesting  GP-INFO-BASIC will return no results at all from a remote machine for some versions of window.

Finally, This API only returns information on the first 25 printers.  Even if there are more, (There is no practical limit).  So it might not be fruitful to request all the printers on a remote server that has more than 25, because you would only get the first 25 returned by this API.

A better way:  For large installations there there may be hundreds of printers to choose from, it may be easier to have the end-users install the drivers for the printers they want to use via the normal Windows Add Printer mechanism.  Then make the call to this API with GET-ALL-MY-PRINTERS set as explained above, and use GP-INFO-BASIC.  This is much faster, and we let Windows do all the heavy lifting.

GP-INFO-LEVEL

There are 88s to specify detailed or basic info level.  Basic returns only Names, ports, and attributes.  See comments in the copybook.

GP-PRINT-COUNT

If you have reason to return less than the maximum (25) printers set this number from 1 to 25.  (There is usually no advantage to this other than not having to poll far away printers on remote networks.  However the order the printers are returned is usually the order in which they were installed on the machine, so this may not yield any reliable improvement in performance.

GP-PRINTER-TABLE-AREA

This is the area that will be returned filled with printer information.   Up to twenty five printers will be displayed.  Do not increase the size of this area.   In the notes below "this machine" refers to the computer running this API.  If running under the Client Server Layer, it usually refers to the client, unless you requested the API to run on the server.

PRINTER-ATTRIBUTES Meaning
GP-ATT-FAX This printer is a Fax  (XP only)
GP-ATT-PUBLISHED This printer has been published (in a Domain or print processor)
GP-ATT-RAW-ONLY No Drivers are to be used - raw data output only
GP-ATT-ENABLE-BIDI Bi Directional data capability.  (Win9x/Me only)
GP-ATT-WORK-OFFLINE Printer is off line
GP-ATT-DOCOMPLETEFIRST Printer will print completely spooled jobs ahead of jobs still spooling
GP-ATT-KEEPJOBS Printer will keep print files around after printing
GP-ATT-ENABLE-DEVQ Printer supports QueryPrint - (knows what forms it has mounted etc)
GP-ATT-LOCAL Is a local printer (On Win9x/me this is unreliable because Win9x does local spooling, and considers any printer for which it has drivers to be local.)
GP-ATT-HIDDEN Printer is hidden - This feature reserved by Microsoft
GP-ATT-NETWORK Network printer 
GP-ATT-SHARED Printer is Shared by this machine
GP-ATT-DEFAULT This is the Default Printer.
GP-ATT-DIRECT-NO-SPOOL Printer prints directly without spooling.
GP-ATT-QUEUED Prints as soon as a page is completed - spools and prints at same time
Printer Information Fields  
GP-PRINTER-NAME The Name of this printer.  Not always available for network printers unless drivers are installed on this machine. Note: Your machine can not get the printer name of a network printer, only the name it is shared under.  Once drivers are installed in this machine, it has the name assigned by the user.  When querying a remote server, this may be a name you can copy files to, of the form \\servername\sharename.  

This  is the Name you would use to print with our Printer APIs.

GP-PORT-NAME Local port name or \\machinename\sharename.  This is usually a destination to which you can copy a file with CopyFile API.  However, when querying the printers attached to a remote server (See GP-SERVER-HOST-NAME above) this may not be something you can open.  In this case, you will have to combine the next two fields into a \\machinename\sharename format, Or use the Printer Name field above.

This is the port you would use to print with our CopyFile APIs

GP-SERVER-NAME When querying for a list of printers attached to a specific domain or computer this is the name of the server.  Usually blank when you query this machine
GP-SHARE-NAME When querying for a list of printers attached to a specific domain or computer this is the name of the share.  Usually blank when you query this machine.
GP-PRINTER-DRIVER-NAME Description of the printer driver installed
GP-PRINTER-COMMENT Comment about this printer added by the user in the printer control panel, or by the server operator for remote printers.
GP-PRINTER-LOCATION Comment about the printer location manually added by the user, or by the server operator if a remote printer.
GP-PRINTER-DEVMODE Complex structure of default printer data, not documented here, may be incomplete.  May be null.
GP-PRINTER-SEPFILE Name of the separator file used between jobs.  May be null.
GP-PRINTER-PRINTPROCESSOR Print Processor used to handle this print. Usually "WinPrint"
GP-PRINTER-DATATYPE Data type printer expects, usually RAW, or EMF or some combination.
GP-PRINTER-PARAMETERS The default printer parameters for each job, used to set up the printer to a known state between jobs.
PRINTER-STATUS Status Meaning  -- SEE NOTE Below
10 GP-STAT-POWER-SAVE Printer is in power save mode
10 GP-STAT-SERVER-UNKNOWN Printer is connected to a server which does not propagate status
10 GP-STAT-DOOR-OPEN Just what it says.
10 GP-STAT-OUT-OF-MEMORY Printer choked on a complex page
10 GP-STAT-USER-INTERVENTION User Intervention required.
10 GP-STAT-PAGE-PUNT Win9x - Page too complex, being purged, can't be printed, not enough printer memory.
10 GP-STAT-NO-TONER Just what it says.
10 GP-STAT-TONER-LOW Not to worry, a few more pages left...
10 GP-STAT-WARMING-UP Patience is a virtue
10 GP-STAT-INITIALIZING Gimmie time...
10 GP-STAT-PROCESSING Preparing to print received pages
10 GP-STAT-NOT-AVAILABLE Can't be reached, or scheduled down time (Win2k/XP only)
10 GP-STAT-WAITING In the middle of receiving a job from somewhere, waiting for more data
10 GP-STAT-OUTPUT-BIN-FULL Just what it says
10 GP-STAT-PRINTING Just what it says
10 GP-STAT-BUSY Working, either receiving data or printing data
10 GP-STAT-IO-ACTIVE Same as above - depending on printer model
10 GP-STAT-OFFLINE Offline button pressed
10 GP-STAT-PAPER-PROBLEM Maybe wrong forms, maybe out of paper - depending on model
10 GP-STAT-MANUAL-FEED Expecting manually fed paper
10 GP-STAT-PAPER-OUT Just what it says
10 GP-STAT-PAPER-JAM Not Again !!!  Cheap paper.
10 GP-STAT-PENDING-DELETION Printer has been deleted - but may still have print pending.
10 GP-STAT-ERROR We don't know what's wrong, but it won't print.
10 GP-STAT-PAUSED Someone pushed the pause button
Tasks  
GP-JOB-COUNT-PENDING Number of jobs queued to this printer

 

WIN32API-PARMS - Used in all GSWINAPI calls

This argument is standard for all CALLs to GSWINAPI. It is used to select the desired API or function, and to return the status of the operation.

WIN32API-RC

Used to return the status of a call to GSWINAPI.  A value of zero is a failure, any other value indicates success.

Recommended usage is to test the 88-level value WIN32API to see if it worked, then to use the text error message to see why it failed.

* ------------------------: If function failed,
*                         :   display the error in a message box.
*
     IF WIN32API-FAILED
       MOVE WIN32API-ERROR-TEXT TO panel-MESSAGE-TEXT
       SET panel-MESSAGE-IN-MESSAGEBOX TO TRUE.

WIN32API-ERROR-CODE

Error code that was returned by Windows.  This is not generally useful unless you have the Windows Platform SDK documentation available to you.

WIN32API-ERROR-TEXT

Plain-text error message that describes why the operation failed.

WIN32API-A through WIN32API-F

The number of these present varies depending on how many arguments are used by the desired function.  These are not used, but must be present because this CALL requires seven arguments.

NOTE Re Printer STATUS:

Microsoft does not check printer status unless something is trying to print.  They don't Poll the printer. Therefore, the status indicators are not reliable unless you just attempted to print something or some other application tried to print something.    Don't complain about this, there is nothing we can do short of queuing up a dummy job and then testing status and then de-queuing the job, which is not something we are likely to do.


2000-2006 Norcom, all rights reserved 

TOC

Send feedback to Norcom