/* 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 #endif #ifndef __CFUUID__ #include #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 :@. 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