/*

    File:       QISA.h

    Contains:   Application support for panel plug-ins.

    Written by: DTS

    Copyright:  Copyright © 2002 by Apple Computer, Inc., All Rights Reserved.

    Disclaimer: IMPORTANT:  This Apple software is supplied to you by Apple Computer, Inc.

                ("Apple") in consideration of your agreement to the following terms, and your

                use, installation, modification or redistribution of this Apple software

                constitutes acceptance of these terms.  If you do not agree with these terms,

                please do not use, install, modify or redistribute this Apple software.

                In consideration of your agreement to abide by the following terms, and subject

                to these terms, Apple grants you a personal, non-exclusive license, under AppleÕs

                copyrights in this original Apple software (the "Apple Software"), to use,

                reproduce, modify and redistribute the Apple Software, with or without

                modifications, in source and/or binary forms; provided that if you redistribute

                the Apple Software in its entirety and without modifications, you must retain

                this notice and the following text and disclaimers in all such redistributions of

                the Apple Software.  Neither the name, trademarks, service marks or logos of

                Apple Computer, Inc. may be used to endorse or promote products derived from the

                Apple Software without specific prior written permission from Apple.  Except as

                expressly stated in this notice, no other rights or licenses, express or implied,

                are granted by Apple herein, including but not limited to any patent rights that

                may be infringed by your derivative works or by other works in which the Apple

                Software may be incorporated.

                The Apple Software is provided by Apple on an "AS IS" basis.  APPLE MAKES NO

                WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED

                WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR

                PURPOSE, REGARDING THE APPLE SOFTWARE OR ITS USE AND OPERATION ALONE OR IN

                COMBINATION WITH YOUR PRODUCTS.

                IN NO EVENT SHALL APPLE BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL OR

                CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE

                GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)

                ARISING IN ANY WAY OUT OF THE USE, REPRODUCTION, MODIFICATION AND/OR DISTRIBUTION

                OF THE APPLE SOFTWARE, HOWEVER CAUSED AND WHETHER UNDER THEORY OF CONTRACT, TORT

                (INCLUDING NEGLIGENCE), STRICT LIABILITY OR OTHERWISE, EVEN IF APPLE HAS BEEN

                ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

    Change History (most recent first):

$Log$

*/

#pragma once

/////////////////////////////////////////////////////////////////

// System interfaces

#if defined(__MACH__)

    #include <Carbon/Carbon.h>

#else

    #include <MacWindows.h>

#endif

// QISA interfaces

#include "QISAPanels.h"

/////////////////////////////////////////////////////////////////

#ifdef __cplusplus

extern "C" {

#endif

extern void QISADisplayError(QISAPanel *panel, OSStatus errNum, CFStringRef actionKey);

    // Displays an error dialog.  errNum is the error code. 

    // It's a If errNum is noErr or userCanceledErr, no error dialog 

    // will be shown.  actionKey represents the action that was being 

    // attempted and failed.  actionKey is localised via the main 

    // application's "Localizable.strings" file.  panel indicates 

    // whether the error was originated by a panel (not NULL) or 

    // by the application as a whole (NULL).  Currently this 

    // information is not used, but in the future it may allow 

    // for the panel to present its own localized error actions.

    // 

    // On entry, panel must either be NULL or point to a valid panel data structure.

    // actionKey must not be NULL

extern Boolean QISAIsPanelValid(const QISAPanel *panel);

    // For debugging.  Returns true if panel is valid.

extern Boolean QISAIsButtonEnabled(QISAPanel *panel, QISAPanelSwitchDirection direction);

    // Returns true if the forward or back button is enabled.

    // 

    // On entry, panel must point to a valid panel data structure.

    // On entry, direction must be either kQISAPanelSwitchDirectionForward 

    // or kQISAPanelSwitchDirectionBackward.

extern void QISASetButtonEnable(QISAPanel *panel, QISAPanelSwitchDirection direction, Boolean enable);

    // Sets the enabled state of either the forward or back button for this panel. 

    // 

    // On entry, panel must point to a valid panel data structure.

    // On entry, direction must be either kQISAPanelSwitchDirectionForward 

    // or kQISAPanelSwitchDirectionBackward.

extern OSStatus QISAGetGlobalValue(const QISAPanel *panel, CFStringRef key, CFPropertyListRef *value);

    // Gets a global value.  These values are initialised from a 

    // configuration dictionary file when the setup window is created.  

    // From that point, the panels can read the values using this 

    // routine, and write them using QISASetGlobalValue.  Changes 

    // are not persistent.  Values are global within a given 

    // setup window, not across the entire application.

    //

    // On entry, panel must point to a valid panel data structure.

    // key must not be NULL, if key is not present, the routine will fail with kCFQKeyNotFoundErr

    // value must not be NULL

    // On success, *value will be non-NULL

    // On error, *value will be NULL

extern OSStatus QISASetGlobalValue(const QISAPanel *panel, CFStringRef key, CFPropertyListRef  value);

    // Gets a global value.  These values are initialised from a 

    // configuration dictionary file when the setup window is created.  

    // From that point, the panels can wrire the values using this 

    // routine, and read them using QISAGetGlobalValue.  Changes 

    // are not persistent.  Values are global within a given 

    // setup window, not across the entire application.

    //

    // On entry, panel must point to a valid panel data structure.

    // key must not be NULL

    // value may be NULL, NULL implies remove

    // if not NULL and value already exists, will replace existing value 

extern OSStatus QISACopyGlobalsDict(const QISAPanel *panel, CFMutableDictionaryRef *result);

    // Returns the entiry global dictionary.  This is a real copy, so 

    // changes to the return dictionary will not affect the actual global 

    // dictionary.  The caller is responsible for releasing the result.

    // 

    // On entry, panel must point to a valid panel data structure.

    // result must not be NULL, *result must be NULL

    // On success, *result will be non-NULL

    // On error, *result will be NULL

// The following are the well known keys within the globals dictionary.

#define kQISAKeyChosenCCL        CFSTR("com.apple.dts.QISA.PortCCLPanel.ChosenCCL")

    // CFString -- The name of the CCL to use.

#define kQISAKeyChosenPort       CFSTR("com.apple.dts.QISA.PortCCLPanel.ChosenPort")

    // CFDictionary -- A dictionary containing information about the port to 

    // use.  Keys within that dictionary are as defined in "QISAPlatform.h".

#define kQISAKeyUsername         CFSTR("com.apple.dts.QISA.UserPassPanel.Username")

    // CFString -- The user name that the user wants to use.

#define kQISAKeyPassword         CFSTR("com.apple.dts.QISA.UserPassPanel.Password")

    // CFString -- The password that the user wants to use.

#define kQISAKeyNumber           CFSTR("com.apple.dts.QISA.UserPassPanel.Number")

    // CFString -- The number to dial.

#define kQISAKeyUseTerminal      CFSTR("com.apple.dts.QISA.UserPassPanel.UseTerminal")

    // CFBoolean -- True if the user wants to use a terminal window to 

    // connect.  This is a really obscure option that's only present 

    // because I need to use it when testing with Apple's dial up servers.

#define kQISAKeySetupUsername    CFSTR("com.apple.dts.QISA.SetupPanel.Username")

#define kQISAKeySetupPassword    CFSTR("com.apple.dts.QISA.SetupPanel.Password")

#define kQISAKeySetupNumber      CFSTR("com.apple.dts.QISA.SetupPanel.Number")

#define kQISAKeySetupUseTerminal CFSTR("com.apple.dts.QISA.SetupPanel.UseTerminal")

    // These keys mirror their UserPassPanel equivalents.  Ultimately 

    // they'll be used to create a temporary account during account setup, 

    // but right now they're not used.

#define kQISAKeyTemporary        CFSTR("com.apple.dts.QISA.Temporary")

    // CFBoolean -- If present and TRUE, use the kQISAKeySetupXxx keys 

    // rather than the kQISAKeyXxx keys.  Again, this isn't used for any 

    // real purpose in the current build.

#define kQISAKeyUserVisibleName  CFSTR("com.apple.dts.QISA.UserVisibleName")

    // CFStringRef -- The user visible name of the network configuration to 

    // create.

#define kQISAKeyPlatformBundle   CFSTR("com.apple.dts.QISA.PlatformBundle")

    // CFStringhRef (CFURL) -- Used by the Mach-O platform to pass the 

    // location of its bundle to the helper setup tool, so that the tool 

    // has access to localised resources.

#define kQISAKeyApplicationSupportFolderName CFSTR("com.apple.dts.QISA.ApplicationSupportFolderName")

    // CFStringRef -- Holds the name of the application's sub-folder within 

    // the "Application Support folder.

#define kQISAKeyControlPanels   CFSTR("com.apple.dts.QISA.ControlPanelsToQuit")

    // CFArrayRef of CFDictionary -- Holds a list of applications to quit 

    // before network setup can proceed.  This list is obtained from the 

    // platform's "PlatformProperties.plist" file.  Each element is a 

    // dictionary with the following keys.

    #define kQISAKeyControlPanelsCreator CFSTR("Creator")

        // The creator of the control panel application.

    #define kQISAKeyControlPanelsType    CFSTR("Type")

        // The type of the control panel application.  You should treat 

        // the key sequence of "????" as a wildcard.

#ifdef __cplusplus

}

#endif