/**

    @name  PrintingPlugins.h

*/

    /**

        @name Introduction

        This documentation lists constants and prototypes needed to use the Printing Plug-ins Manager

    */

/*

    File:       PrintingPlugins.h

    Contains:   Constants needed to create Printing Plug-ins.

                Constants and prototypes needed to use the Printing Plug-ins Manager

    Version:    Technology: PrintingLib 8.6.5

                Release:    1.0

    Copyright:  © 1999 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/

*/

/*

*   Change History (most recent first):

*

*   05/22/99    jb340   More documentation efforts. (Unmarked except here.)

*

*/

#ifndef __PrintingPlugins__

#define __PrintingPlugins__

#if !defined(rez) && !defined(derez)

#if PRAGMA_ONCE

#pragma once

#endif

#ifndef __MACTYPES__

#include <MacTypes.h>

#endif

#ifndef __FILES__

#include <Files.h>

#endif

#endif

#ifdef __cplusplus

extern "C" {

#endif

#if !defined(rez) && !defined(derez)

#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

#endif

/**

    @name Printing Plugin Defines and Enums

*/

/**

    #kPluginResourceInfo# 

    The Type and ID of the the resource needed by Printing Plug-in modules. The

    resource definition of this resource type is contained in PrintingPlugins.r

*/

#define kPluginResourceInfoType     'PLGN'

#define kPluginResourceInfoID       -8192

#if !defined(rez) && !defined(derez)

/// The Finder file type for auto routing of items to go into the Printing Plug-ins Folder.

/**

    @name PrintingPlugInsFileType

    more info needed!!!!!!!!

*/

    /** PrintingPlugInsFileType */

    enum{

        /// info needed!!!

        kPrintingPlugInsFileType = FOUR_CHAR_CODE('bird')

    };

#endif

/*

    This is the list of reserved Printing Plug-ins Manager 'types' of plug-ins in use by system software.

    This 'type' is not the Finder type of the file but instead is that used in the 'type' field of the

    'PLGN' resource required for use by the Printing Plug-ins Manager. 

*/

/**

    #kDownloadMgrPluginType# 

    Download Manager plugin converter modules

*/

#define kDownloadMgrPluginType  'down'

/**

    #kHosePluginType#

    Output communications plugin modules 

*/

#define kHosePluginType         'hose'

/**

    #kDTPUPluginType#

    Desktop Printer Utility UI plugin modules

*/

#define kDTPUPluginType         'dtpu'  

#define kPSOutputFilterPlugInType 'Fltr'    /* PostScript Output Filter modules */

/****** Types *****/

/**

    @name Printing Plugin Variable Types

*/

/*

    Only users of the Printing Plug-ins Manager API need these typedefs. They are not relevant to 

    developers of plug-ins.

*/

#if !defined(rez) && !defined(derez)

/* abstract data type for CacheData */

    typedef struct PrivateCacheDataRecord *CacheData;

/**

    @name SettingsDataType

    An OSType which contains the type of the library.

*/

    typedef OSType SettingsDataType;

/**

    @name SettingsDataSubType

    An OSType which contains the subtype of the library.

*/

    typedef OSType SettingsDataSubType;

/**

    @name LibraryLocator

    A structure which can be used by a client to open a particular shared library using #GetDiskFragment()#.

    It contains information about the #FSSpec#, the library name, and, for the currently executing architecture,

    the offset of the shared library in the file and the libraryÕs length.

*/

    /** LibraryLocator */ 

    struct LibraryLocator{

        /// the fileSpec for the file containing the plug-in 

        FSSpec  librarySpec;

        /// the fragment name of the plug-in shared library 

        Str63   libraryName;

        /// the offset to the fragment 

        SInt32  libraryOffset;          

        /// the length of the fragment 

        SInt32  libraryLength;          

    };

    typedef struct LibraryLocator LibraryLocator, *LibraryLocatorListP, **LibraryLocatorListH;

/**

    @name LibraryData

    more info needed

*/

    /** LibraryData */

    struct LibraryData{

        /// subtype

        SettingsDataSubType subtype;

        /// libraryLocator

        LibraryLocator libraryLocator;

    };

    typedef struct LibraryData LibraryData, *LibraryDataListP, **LibraryDataListH;

enum {

    uppClientBuildCacheDataProcInfo = kPascalStackBased

     | RESULT_SIZE(SIZE_CODE(sizeof(OSStatus)))

     | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(LibraryLocator *)))

     | STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(void *)))

     | STACK_ROUTINE_PARAMETER(3, SIZE_CODE(sizeof(SettingsDataSubType)))

     | STACK_ROUTINE_PARAMETER(4, SIZE_CODE(sizeof(CacheData)))

};

enum {

    uppClientProcessCacheDataProcInfo = kPascalStackBased

     | RESULT_SIZE(SIZE_CODE(sizeof(OSStatus)))

     | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(LibraryLocator *)))

     | STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(void *)))

     | STACK_ROUTINE_PARAMETER(3, SIZE_CODE(sizeof(SInt32)))

     | STACK_ROUTINE_PARAMETER(4, SIZE_CODE(sizeof(void *)))

     | STACK_ROUTINE_PARAMETER(5, SIZE_CODE(sizeof(Boolean *)))

};

typedef pascal OSStatus (*ClientBuildCacheDataCallBack)(const LibraryLocator *thisLocator, void *clientrefcon, 

                                SettingsDataSubType subtype, CacheData cache);          

typedef pascal OSStatus (*ClientProcessCacheDataCallBack)(const LibraryLocator *thisLocator, void *clientrefcon, 

                                SInt32 size, const void *dataPtr, Boolean *addThisLocator);

#if TARGET_RT_MAC_CFM

    typedef UniversalProcPtr ClientBuildCacheDataCallBackUPP;

    #define CallClientBuildCacheDataProc(userRoutine, thisLocator, clientrefcon, subtype, cache)        \

            CallUniversalProc(userRoutine, uppClientBuildCacheDataProcInfo, \

                (thisLocator), (clientrefcon), (subtype), (cache))

#else

    typedef ClientBuildCacheDataCallBack ClientBuildCacheDataCallBackUPP;

    #define CallClientBuildCacheDataProc(userRoutine, thisLocator, clientrefcon, subtype, cache)        \

            (*userRoutine)( (thisLocator), (clientrefcon), (subtype), (cache) )

#endif

#if TARGET_RT_MAC_CFM

    typedef UniversalProcPtr ClientProcessCacheDataCallBackUPP;

    #define CallClientProcessCacheDataCallBackProc(userRoutine, thisLocator, clientrefcon, size, dataPtr, addThisLocator)       \

            CallUniversalProc(userRoutine, uppClientProcessCacheDataProcInfo, \

                (thisLocator), (clientrefcon), (size), (dataPtr), (addThisLocator))

#else

    typedef ClientProcessCacheDataCallBack ClientProcessCacheDataCallBackUPP;

    #define CallClientProcessCacheDataCallBackProc(userRoutine, thisLocator, clientrefcon, size, dataPtr, addThisLocator)       \

            (*userRoutine)( (thisLocator), (clientrefcon), (size), (dataPtr), (addThisLocator) )

#endif

/****** ProtoTypes ******/

/**

    @name Printing Plugin Prototypes

*/

    /*

        Only users of the Printing Plug-ins Manager API need these prototypes. They are not relevant to 

        developers of printing plug-ins.

    */

    /** 

        Locates, and creates if needed, the current system's Printing Plug-ins folder. On exit, 

        the #*vrefP# and #*folderIDP# correspond to to the Printing Plug-ins folder. If the folder

        does not exist and cannot be created, then an error is returned.

        @param  vrefP   a pointer to a #short# which represents, on exit, the refnum of the Printing Plug-ins folder.

        @param  folderIDP   a pointer to a #long# which represents, on exit, the ID of the Printing Plug-ins folder. 

        @return a non-zero error if the folder does not exist or cannot be created.

    */

    OSStatus psGetPrintingPluginsFolder(short *vrefP, long *folderIDP);

    /** 

        Returns a pointer to the localized name of the Printing Plug-ins folder.

        This pointer is valid as long as the Settings library is loaded in memory.

        @return a #StringPtr# with the localized name of the Printing Plug-ins folder.

    */

    StringPtr psGetPrintingPluginsFolderName(void);

    /** 

        Returns a pointer to the localized name of the Printing Plug-ins Preferences file.

        The pointer is valid as long as the Settings library is loaded in memory.

        @return a #StringPtr# with the localized name of the Printing Plug-ins Preferences file.        

    */

    StringPtr psGetPluginPrefsFileName();               

    /**

        Takes a type and subtype and returns a handle containing a list of LibraryLocators for all the 

        plug-ins which advertise that they can handle that type and subtype. Upon return, #*numLocatorsP# is the number 

        of LibraryLocators which were found and #*locatorListHP# is a handle containing a list of the found LibraryLocators.

        If #*numLocatorsP# is zero, then the returned value of #*locatorListHP# is NULL. 

        The caller is responsible for disposing of any handle returned in #*locatorListHP#.

        @param  type    a #SettingsDataType# structure representing the desired type. 

        @param  subtype a #SettingsDataType# structure representing the desired subtype.

        @param  numLocatorsP    a pointer to a #long# which represents the number of LibraryLocators which were found. 

        @param  libraryListHP   a pointer to a #LibraryDataListH# structure which  contains a list of LibraryData

                                structures that can handle #type#. 

        @return a non-zero error if the list of cannot be returned.

        @see SettingsDataType

        @see LibraryLocatorListH

*/

    OSStatus psGetSubtypeLocators(SettingsDataType type, SettingsDataSubType subtype, long *numLocatorsP, 

                                        LibraryLocatorListH *locatorListHP);

    /** 

        Takes a type and subtype and returns a list of LibraryLocators for all the 

        plug-ins which advertise that they can handle that type and subtype. 

        This flavor of this routine allows a client to specify data to be cached by the plug-in

        manager through the buildcallback, and to use that data to help the Printing Plug-ins

        Manager to narrow the list of plug-ins by using that data in processcallback.

        The client supplies a clientDataVersion to be added to the information the Printing Plug-ins Manager uses

        to determine if its cache is up to date. This allows clients to revise the data format they are caching and

        avoid getting 'old' data out of the cache. 

        NOTE: Negative values for clientDataVersion are reserved by the implementation.

        Upon successful completion, *numLocatorsP contains the number of LibraryLocators specified during processcallback

        and *locatorListHP is a handle containing the list of LibraryLocators. If *numLocatorsP is zero, then *locatorListHP

        is NULL.

        The caller is responsible for disposing of any handle returned in *locatorListHP.

        @param  type  a #SettingsDataType# structure representing the desired type.

        @param  subtype  a #SettingsDataType# structure representing the desired subtype.

        @param  clientDataVersion   a #SInt32# structure which represents the added information the printing Plug-ins manager

                                    uses to determine if its cache is up to date.  

        @param  buildcallback   a #ClientBuildCacheDataCallBackUPP# procedure which allows data to be cached by  

                                the plug-in manager.

        @param  processcallback a #ClientProcessCacheDataCallBackUPP# procedure which represents data that helps the Printing Plug-ins Manager 

                                narrow the list of plug-ins.

        @param  clientrefcon    any other client supplied data that may be necessary.

        @param  numLocatorsP    a pointer to a #long# which represents the number of LibraryLocators specified during processcallback.

        @param  locatorListHP   a pointer to a #LibraryLocatorListH# structure which represents a handle containing the list of LibraryLocators.

        @return a non-zero error if a list of LibraryLocators could not be returned.

        @see SettingsDataType

        @see LibraryLocatorListH

    */

    OSStatus psGetPreferredSubtypeLocators(SettingsDataType type, SettingsDataSubType subtype, SInt32 clientDataVersion,

                        ClientBuildCacheDataCallBackUPP buildcallback, 

                        ClientProcessCacheDataCallBackUPP processcallback, 

                        void *clientrefcon, long *numLocatorsP, LibraryLocatorListH *locatorListHP);

    /** 

        Used by the ClientBuildCacheDataCallBackUPP routine to add data for each subtype to the cacheData being

        built for the type specified in the #psGetPreferredSubtypeLocators()# routine.

        Adds data for each subtype to the cacheData being built for the type specified in the 

        #psGetPreferredSubtypeLocators()# routine.

        @param  cache   a #CacheData# structure which is built for the type specified in the

                        #psGetPreferredSubtypeLocators()# routine.

        @param  subtype a #SettingsDataType# structure representing the desired subtype. 

        @param  size    a #SInt32# structure which represents

        @param  dataPtrP the data to be added.

        @return a non-zero error if the data for each subtype could not be added to the cacheData.

        @see SettingsDataType

    */

    OSStatus psAddSettingsSubTypeData(CacheData cache, SettingsDataSubType subtype, SInt32 size, const void *dataPtrP);

    /**

        #psValidateLibraryLocator# validates a library locator as being valid. If the library in the *libLocatorP differs

        from that in the actual file or the containing file does not exist, then this routine returns false in *isValidP, 

        otherwise it returns true.

        Validates a library locator as being valid.

        @param  libLocatorP a #*LibraryLocator# structure which reflects the library in the actual file.

        @param  isValidP    reflects whether the library in the *libLocatorP differs from that in the actual file or the 

                            containing file does not exist.

        @return a non-zero error if the library locator is not valid.

        @see LibraryLocator

    */

    OSStatus psValidateLibraryLocator(const LibraryLocator *libLocatorP, Boolean *isValidP);

    /**     

        Takes a type and returns a list of LibraryData structures for all the printing plug-ins  

        which advertise that they can handle that type.

        Upon successful completion, *numLibrariesP contains the number of printing plug-ins found and *libraryListHP

        contains a handle with a list of LibraryData structures for each plug-in. If *numLibrariesP is zero

        then *libraryListHP will be NULL.

        The caller is responsible for disposing of any handle returned in *libraryListHP.

        If you know the subtype of the libraries you are interested in, then the call psGetSubtypeLocators

        is strongly recommended instead of this call. The #psGetSubtypeLocators# call caches data to improve

        performance whereas psGetTypeLibraryData always looks at all the libraries in PrintingLib and the Printing 

        Plug-ins folder.

        This call was added as of PrintingLib version 8.6.5.

        @param  type    a #SettingsDataType# structure representing the desired type.   

        @param  numLibrariesP  a pointer to #long# which represents the number of printing plug-ins found.

        @param  libraryListHP   a pointer to a #LibraryDataListH# structure which  contains a list of LibraryData

                                structures that can handle #type#.

        @return a non-zero error if the list of cannot be returned.

        @see SettingsDataType

        @see LibraryDataListH

    */

    OSStatus psGetTypeLibraryData(SettingsDataType type, long *numLibrariesP, LibraryDataListH *libraryListHP);

#endif          

#if !defined(rez) && !defined(derez)

#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

#endif

#ifdef __cplusplus

}

#endif

#endif      /* __PrintingPlugins__ */