You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
301 lines
12 KiB
301 lines
12 KiB
/* |
|
File: PMPrinterBrowsers.h |
|
|
|
Contains: Mac OS X Printing Manager Printer Browser Module Interfaces |
|
|
|
Version: QuickTime 7.3 |
|
|
|
Copyright: (c) 2007 (c) 1999-2001 by Apple Computer, Inc., all rights reserved |
|
|
|
Bugs?: For bug reports, consult the following page on |
|
the World Wide Web: |
|
|
|
http://developer.apple.com/bugreporter/ |
|
|
|
*/ |
|
#ifndef __CONTROLS__ |
|
#include <Controls.h> |
|
#endif |
|
|
|
#ifndef __CFUUID__ |
|
#include <CFUUID.h> |
|
#endif |
|
|
|
|
|
|
|
#if PRAGMA_ONCE |
|
#pragma once |
|
#endif |
|
|
|
#ifdef __cplusplus |
|
extern "C" { |
|
#endif |
|
|
|
#if PRAGMA_IMPORT |
|
#pragma import on |
|
#endif |
|
|
|
#if PRAGMA_STRUCT_ALIGN |
|
#pragma options align=mac68k |
|
#elif PRAGMA_STRUCT_PACKPUSH |
|
#pragma pack(push, 2) |
|
#elif PRAGMA_STRUCT_PACK |
|
#pragma pack(2) |
|
#endif |
|
|
|
/* |
|
Current version of the printer browser module API, which specifies the format |
|
of the functions and various structures used in the API. |
|
*/ |
|
#define kPMPrBrowserAPIVersion 1 |
|
/* |
|
Constants required for retrieving standard icons supplied by PrintCenter... |
|
|
|
Any standard icons supplied by PrintCenter for use in displaying printer |
|
browser HI will have been registered with Icon Services when the printer |
|
browser module is loaded. The printer browser module need only call GetIconRef() |
|
with the appropriate constants to obtain a reference to the required icon. |
|
|
|
PrintCenter creator code. |
|
*/ |
|
enum { |
|
kPMPrBrowserPCCreator = FOUR_CHAR_CODE('pctr'), |
|
kPMPrBrowserWorksetPrinterIconType = FOUR_CHAR_CODE('wspr'), |
|
kPMPrBrowserUnknownPrinterIconType = FOUR_CHAR_CODE('?ptr') |
|
}; |
|
|
|
/* |
|
PrintCenter flags... |
|
|
|
These flags are passed by PrintCenter in the Prologue() function. |
|
*/ |
|
typedef UInt32 PMPrBrowserFlags; |
|
enum { |
|
kPMPrBrowserPCNoFlags = 0x00000000, /* Empty flag word. */ |
|
kPMPrBrowserPCNoUI = 0x00000001, /* PBM will be loaded without UI. */ |
|
kPMPrBrowserPCAllFlags = (unsigned long)0xFFFFFFFF /* All flags set. */ |
|
}; |
|
|
|
/* |
|
Printer browser module CFPlugIn constants. |
|
|
|
Define the CFPlugIn Type for printer browser modules. All printer browser modules |
|
must be plug-ins of this type. |
|
|
|
Users of these IDs should convert these to CFStrings (probably using the CFSTR |
|
macro) and then call CFUUIDCreateFromString() to obtain a CFUUIDRef. Note that |
|
the CFUUIDRef may refer to an existing CFUUID, so the caller should call |
|
CFRelease() on the CFUUIDRef() when he no longer needs it. |
|
*/ |
|
#define kPMPrBrowserPlugInType "23F71E46-95CC-1226-AC04-000502ADB00B" |
|
/* |
|
Define the ID of the Interface that supplies the APIVersion() function. All |
|
printer browser modules must supply this Interface. |
|
*/ |
|
#define kPMInterfaceAPIVersion "1D6BF822-95D0-1226-A8ED-000502ADB00B" |
|
/* |
|
Define the ID of the Interface that supplies the printer browser module API. All |
|
printer browser modules must supply this Interface. |
|
*/ |
|
#define kPMInterfacePrBrowser "86544C22-95D0-1226-91D5-000502ADB00B" |
|
|
|
/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
Type Definitions |
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/ |
|
typedef struct OpaquePMPrBrowserRef* PMPrBrowserRef; |
|
typedef struct OpaquePMPrBrowserContext* PMPrBrowserContext; |
|
/* |
|
Invalid printer browser reference number. |
|
*/ |
|
#define kPMPrBrowserInvalidRef ((PMPrBrowserRef)(-1)) |
|
/* |
|
Printer browser module-specific keys for the printer lookup specification |
|
dictionary. This CFDictionary is supplied by the printer module and provides |
|
the printer browser module with the information it needs to browse for a given |
|
type of printer over its connection type, and to display it in the browser |
|
view. |
|
|
|
The printer module supplies the following keys and values (these are more |
|
fully defined in PMPrinterModule.h): |
|
|
|
kPMPrBrowserLookupKindKey: a CFStringRef to a human-readable printer type |
|
string that can be displayed in the browser view. |
|
|
|
kPMPrBrowserLookupInfoKey: a CFPropertyListRef to connection-specific |
|
information used to look up a particular kind of printer over a given IO |
|
connection. |
|
|
|
kPMPrBrowserLookupIconKey: a CFDataRef to the icon family data for the |
|
printer icon to be displayed in the browser view. |
|
|
|
In addition, PrintCenter adds the following information to the lookup |
|
specification dictionary: |
|
|
|
kPMPrBrowserLookupRefKey: a CFTypeRef to PrintCenter-specific information |
|
that must be returned by the printer browser module in the printer selection |
|
specfication dictionary (see below) when a printer is selected that was |
|
located using this lookup specification. |
|
|
|
PrintCenter informs the printer browser module of the number of lookup |
|
specification dictionaries that are available when the module's Initialize() |
|
function is called. Thereafter, the printer browser module can obtain |
|
a copy of any of the lookup specification dictionaries by calling the |
|
PMPrBrowserGetLookupSpec callback and specifying an index between 0 and n-1, |
|
where n is the number of lookup specification dictionaries. |
|
|
|
PrintCenter creates a full copy of the printer lookup specification dictionary |
|
before passing it to the printer browser module; the printer browser module |
|
should call ::CFRelease() on the dictionary when it is no longer needed. |
|
*/ |
|
#define kPMPrBrowserLookupRefStr "PrBrowser Lookup Reference" |
|
#define kPMPrBrowserLookupRefKey CFSTR("PrBrowser Lookup Reference") |
|
/* |
|
Keys for the printer selection specification dictionary. This CFDictionary |
|
specifies the printers selected in the browser view. An array of these |
|
dictionaries is is passed back to PrintCenter when it calls the printer |
|
browser module's GetSelectedPrinters() function. |
|
|
|
An array of selection specification dictionaries is passed from PrintCenter |
|
to the printer browser module when PrintCenter calls the WorksetPrinters() |
|
function. These dictionaries specify which printers are already in the |
|
Workset. The printer browser module can use this information to indicate in |
|
its UI whether a printer has been added to the Workset. It can also use |
|
this information in non-UI mode to avoid supplying duplicate printers during |
|
automatic printer discovery. |
|
|
|
kPMPrBrowserSelectNameKey corresponds to a CFStringRef to a human-readable |
|
printer name string, obtained from the printer or otherwise constructed by |
|
the printer browser module. |
|
|
|
kPMPrBrowserSelectKindKey corresponds to a CFStringRef to a human-readable |
|
printer description string that can be displayed in the PrintCenter Workset |
|
window. For printer that uses Apple's PostScript printer module over an |
|
AppleTalk connection, this would be the string "PostScript printer". Often |
|
this is the same as the string corresponding to kPMPrBrowserLookupKindKey |
|
in the printer lookup specification dictionary, but it is possible that |
|
more specific printer model information might be obtained by the printer |
|
browser module during the lookup. |
|
|
|
kPMPrBrowserSelectAddrKey corresponds to a CFDataRef to a connection-specific |
|
address specification for the printer. On an AppleTalk connection, this would |
|
be a standard NBP address of the form <name>:<type>@<zone>. |
|
|
|
kPMPrBrowserSelectRefKey corresponds to a CFTypeRef whose value is the same |
|
as that corresponding to kPMPrBrowserLookupRefKey in the printer lookup |
|
specification dictionary. The reference value in the lookup specification |
|
dictionary that was used to locate the selected printer must be copied into |
|
the printer selection specification dictionary and assigned this key. |
|
|
|
When PrintCenter supplies printer selection specification dictionaries using |
|
the WorksetPrinters() function, the dictionaries do not contain a |
|
kPMPrBrowserSelectRefKey entry; the printer browser module should not expect |
|
to find a corresponding value for this key in those dictionaries. |
|
|
|
PrintCenter gets information about selected printers when it calls the |
|
printer browser module's GetSelectedPrinters() function. |
|
|
|
PrintCenter will call ::CFRelease() on the printer selection specification |
|
dictionary when it is no longer needed. |
|
|
|
The printer browser module should call ::CFRelease() on the array of |
|
printer selection specification dictionaries supplied via the WorksetPrinters() |
|
function when they are no longer needed. |
|
*/ |
|
#define kPMPrBrowserSelectNameStr "PrBrowser Selection Name" |
|
#define kPMPrBrowserSelectNameKey CFSTR("PrBrowser Selection Name") |
|
#define kPMPrBrowserSelectKindStr "PrBrowser Selection Kind" |
|
#define kPMPrBrowserSelectKindKey CFSTR("PrBrowser Selection Kind") |
|
#define kPMPrBrowserSelectAddrStr "PrBrowser Selection Address" |
|
#define kPMPrBrowserSelectAddrKey CFSTR("PrBrowser Selection Address") |
|
#define kPMPrBrowserSelectRefStr "PrBrowser Selection Reference" |
|
#define kPMPrBrowserSelectRefKey CFSTR("PrBrowser Selection Reference") |
|
/* |
|
PrintCenter callback routines for printer browser modules. |
|
*/ |
|
typedef CALLBACK_API_C( OSStatus , PMPrBrowserGetLookupSpecProcPtr )(PMPrBrowserRef ref, UInt32 specIndex, CFDictionaryRef *lookupSpec); |
|
typedef CALLBACK_API_C( OSStatus , PMPrBrowserSelectionStatusProcPtr )(PMPrBrowserRef ref, Boolean selected, Boolean addNow); |
|
typedef CALLBACK_API_C( OSStatus , PMPrBrowserSyncRequestProcPtr )(PMPrBrowserRef ref); |
|
/* |
|
Callback parameter block. |
|
*/ |
|
struct PMPrBrowserCallbacks { |
|
CFIndex version; /* Version number; always set to kPMPrBrowserAPIVersion. */ |
|
|
|
PMPrBrowserGetLookupSpecProcPtr getLookupSpec; |
|
PMPrBrowserSyncRequestProcPtr syncRequest; |
|
PMPrBrowserSelectionStatusProcPtr selStatus; |
|
}; |
|
typedef struct PMPrBrowserCallbacks PMPrBrowserCallbacks; |
|
typedef PMPrBrowserCallbacks * PMPrBrowserCallbacksPtr; |
|
/* |
|
Required entry points for printer browser modules... |
|
*/ |
|
typedef CALLBACK_API_C( UInt32 , PMPrBrowserAPIVersionProcPtr )(void); |
|
typedef CALLBACK_API_C( OSStatus , PMPrBrowserGetSelectedPrintersProcPtr )(PMPrBrowserContext context, CFArrayRef *printers); |
|
typedef CALLBACK_API_C( OSStatus , PMPrBrowserInitializeProcPtr )(PMPrBrowserContext context, PMPrBrowserRef ref, PMPrBrowserCallbacks *callbacks, ControlRef pbUserPaneCtlHdl, UInt32 numLookupSpecs); |
|
typedef CALLBACK_API_C( OSStatus , PMPrBrowserPrologueProcPtr )(PMPrBrowserContext *context, PMPrBrowserFlags prologueFlags, CFStringRef *title, UInt32 *minH, UInt32 *minV, UInt32 *maxH, UInt32 *maxV); |
|
typedef CALLBACK_API_C( OSStatus , PMPrBrowserResizeProcPtr )(PMPrBrowserContext context, const Rect *frameRect); |
|
typedef CALLBACK_API_C( OSStatus , PMPrBrowserSyncProcPtr )(PMPrBrowserContext context); |
|
typedef CALLBACK_API_C( OSStatus , PMPrBrowserTerminateProcPtr )(PMPrBrowserContext context, OSStatus status); |
|
typedef CALLBACK_API_C( OSStatus , PMPrBrowserWorksetPrintersProcPtr )(PMPrBrowserContext context, CFArrayRef printers); |
|
typedef CALLBACK_API_C( SInt32 , PMCOMQueryInterfaceProcPtr )(void *thisPointer, CFUUIDBytes iid, void **ppv); |
|
typedef CALLBACK_API_C( UInt32 , PMCOMAddRefProcPtr )(void * thisPointer); |
|
typedef CALLBACK_API_C( UInt32 , PMCOMReleaseProcPtr )(void * thisPointer); |
|
/* |
|
Same as IUnknownVTbl from CFPluginCOM.h, but we don't want to drag in that header |
|
because it defines many Windows types that could collide with other definitions |
|
*/ |
|
struct PMIUnknownVTbl { |
|
void * _reserved; |
|
PMCOMQueryInterfaceProcPtr QueryInterface; |
|
PMCOMAddRefProcPtr AddRef; |
|
PMCOMReleaseProcPtr Release; |
|
}; |
|
typedef struct PMIUnknownVTbl PMIUnknownVTbl; |
|
/* |
|
Define the Interface structures returned by Factories. |
|
|
|
PMInterfaceAPIVersion Interface... |
|
*/ |
|
struct PMInterfaceAPIVersion { |
|
PMIUnknownVTbl u; /* Supplies COM compatibility; required of all CFPlugIns. */ |
|
|
|
PMPrBrowserAPIVersionProcPtr apiVersion; |
|
}; |
|
typedef struct PMInterfaceAPIVersion PMInterfaceAPIVersion; |
|
typedef PMInterfaceAPIVersion * PMInterfaceAPIVersionPtr; |
|
/* |
|
PMInterfacePrBrowser Interface... |
|
*/ |
|
struct PMInterfacePrBrowser { |
|
PMIUnknownVTbl u; /* Supplies COM compatibility; required of all CFPlugIns. */ |
|
|
|
/*Required entry points.*/ |
|
PMPrBrowserGetSelectedPrintersProcPtr getSelectedPrinters; |
|
PMPrBrowserInitializeProcPtr initialize; |
|
PMPrBrowserPrologueProcPtr prologue; |
|
PMPrBrowserResizeProcPtr resize; |
|
PMPrBrowserSyncProcPtr sync; |
|
PMPrBrowserTerminateProcPtr terminate; |
|
PMPrBrowserWorksetPrintersProcPtr worksetPrinters; |
|
}; |
|
typedef struct PMInterfacePrBrowser PMInterfacePrBrowser; |
|
typedef PMInterfacePrBrowser * PMInterfacePrBrowserPtr; |
|
|
|
#if PRAGMA_STRUCT_ALIGN |
|
#pragma options align=reset |
|
#elif PRAGMA_STRUCT_PACKPUSH |
|
#pragma pack(pop) |
|
#elif PRAGMA_STRUCT_PACK |
|
#pragma pack() |
|
#endif |
|
|
|
#ifdef PRAGMA_IMPORT_OFF |
|
#pragma import off |
|
#elif PRAGMA_IMPORT |
|
#pragma import reset |
|
#endif |
|
|
|
#ifdef __cplusplus |
|
} |
|
#endif
|
|
|