GUI ScreenIO for Windows |
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.
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 |
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 available to copy to your system:
COPY WIN32API.
SET GP-GET-ALL-MY-PRINTERS TO
TRUE |
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.
There are 88s to specify detailed or basic info level. Basic returns only Names, ports, and attributes. See comments in the copybook.
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.
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 |
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.
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,
|
Error code that was returned by Windows. This is not generally useful unless you have the Windows Platform SDK documentation available to you.
Plain-text error message that describes why the operation failed.
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.
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-2019 Norcom, all rights reserved |