prj/tech/libsrc/compapis/appapi.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // $Source: x:/prj/tech/libsrc/compapis/RCS/appapi.h $
   3 // $Author: TOML $
   4 // $Date: 1997/08/05 13:12:03 $
   5 // $Revision: 1.20 $
   6 //
   7 // Specification of generic "Application" interface.  App could implement
   8 // this.  Libraries provide a generic implementation.  Generic things common to
   9 // all applications, game or not.
  10 //
  11
  12 #ifndef __APPAPI_H
  13 #define __APPAPI_H
  14
  15 #if defined(__SC__) || defined(__RCC__)
  16 #pragma once
  17 #endif
  18
  19 ///////////////////////////////////////
  20
  21 // Expected includes:
  22 //  "lg.h"
  23 //  "comtools.h"
  24
  25 #include "appguid.h"
  26
  27 ///////////////////////////////////////////////////////////////////////////////
  28
  29 F_DECLARE_INTERFACE(IApplication);
  30 F_DECLARE_INTERFACE(IAppAdviseSink);
  31
  32 ///////////////////////////////////////////////////////////////////////////////
  33 //
  34 // Create a generic application and add it to the global app-object
  35 //
  36
  37 #define GenericApplicationCreate(argc, argv, name, defaultPath) \
  38 { \
  39     IUnknown * pAppUnknown = AppGetObj(IUnknown); \
  40     _GenericApplicationCreate(IID_TO_REFIID(IID_IApplication), NULL, pAppUnknown, argc, argv, name, defaultPath);\
  41     COMRelease(pAppUnknown); \
  42 }
  43
  44 //
  45 // Creates a generic application, aggregating it with specfied pOuter,
  46 // use IAggregate protocol if ppApplication is NULL, else self-init
  47 //
  48
  49 EXTERN tResult LGAPI _GenericApplicationCreate(REFIID, IApplication ** ppApplication, IUnknown * pOuter, int argc, const char *argv[], const char * pszName, const char * pszDefaultPath);
  50
  51 ///////////////////////////////////////////////////////////////////////////////
  52 //
  53 // INTERFACE: IApplication
  54 //
  55 //
  56
  57 #undef  INTERFACE
  58 #define INTERFACE IApplication
  59
  60 DECLARE_INTERFACE_(IApplication, IUnknown)
  61 {
  62     //
  63     // IUnknown methods
  64     //
  65     DECLARE_UNKNOWN_PURE();
  66
  67     //
  68     // Quit the application (conditional, non-error), return non-zero to not quit
  69     //
  70     STDMETHOD (QueryQuit)(THIS) PURE;
  71
  72     //
  73     // Quit the application (unconditional, non-error)
  74     //
  75     STDMETHOD_(void, Quit)(THIS) PURE;
  76
  77     //
  78     // Quit the application (unconditional, error)
  79     //
  80     STDMETHOD_(void, Abort)(THIS_ const char * pszReason) PURE;
  81
  82     //
  83     // Get/Set application name, as displayed in title bar
  84     //
  85     STDMETHOD_(void, SetCaption)(THIS_ const char *) PURE;
  86     STDMETHOD_(const char *, GetCaption)(THIS) PURE;
  87
  88     //
  89     // Get/Set default path for file access
  90     //
  91     STDMETHOD_(void, SetDefaultFilePath)(THIS_ const char *) PURE;
  92     STDMETHOD_(const char *, GetDefaultFilePath)(THIS) PURE;
  93
  94     //
  95     // Get the full path of the application .EXE
  96     // i.e., c:\foo\bar.exe
  97     //
  98     STDMETHOD_(const char *, GetFullName)(THIS) PURE;
  99
 100     //
 101     // Get the full path of the application .EXE
 102     // i.e., c:\foo
 103     //
 104     STDMETHOD_(const char *, GetPath)(THIS) PURE;
 105
 106     //
 107     // Display a message box
 108     //
 109     STDMETHOD_(int, MessageBox)(THIS_ const char * pszMessage, const char * pszCaption, int fFlags) PURE;
 110
 111     //
 112     // Advise/Unadvise for sink/holder protocol
 113     //
 114     STDMETHOD (Advise)(THIS_ IAppAdviseSink * pSink, DWORD * pCookie) PURE;
 115     STDMETHOD (Unadvise)(THIS_ DWORD cookie) PURE;
 116
 117     //
 118     // Fire a command
 119     //
 120     STDMETHOD_(void, AppCommand)(THIS_ unsigned nCmdId) PURE;
 121
 122 };
 123
 124 ///////////////////////////////////////
 125
 126 #define IApplication_QueryInterface(p, a, b)    COMQueryInterface(p, a, b)
 127 #define IApplication_AddRef(p)                  COMAddRef(p)
 128 #define IApplication_Release(p)                 COMRelease(p)
 129 #define IApplication_QueryQuit(p)               COMCall0(p, QueryQuit)
 130 #define IApplication_Quit(p)                    COMCall0(p, Quit)
 131 #define IApplication_Abort(p, a)                COMCall1(p, Abort, a)
 132 #define IApplication_SetCaption(p, a)           COMCall1(p, SetCaption, a)
 133 #define IApplication_GetCaption(p)              COMCall0(p, GetCaption)
 134 #define IApplication_SetDefaultFilePath(p, a)   COMCall1(p, SetDefaultFilePath, a)
 135 #define IApplication_GetDefaultFilePath(p)      COMCall0(p, GetDefaultFilePath)
 136 #define IApplication_GetFullName(p)             COMCall0(p, GetFullName)
 137 #define IApplication_GetPath(p)                 COMCall0(p, GetPath)
 138 #define IApplication_MessageBox(p, a, b, c)     COMCall3(p, MessageBox, a, b, c)
 139 #define IApplication_Advise(p, a, b)            COMAdvise(p, a, b)
 140 #define IApplication_Unadvise(p, a)             COMUnadvise(p, a)
 141
 142 ///////////////////////////////////////////////////////////////////////////////
 143 //
 144 // INTERFACE: IAppAdviseSink
 145 //
 146 //
 147
 148 #define kVerAppAdvise 2
 149 // Version 1:
 150 //      Original interface
 151 #define kVerAppAdvise_Original 1
 152 // Version 2:
 153 //      Command support
 154 #define kVerAppAdvise_CommandSupport 2
 155
 156 ///////////////////////////////////////
 157
 158 #undef  INTERFACE
 159 #define INTERFACE IAppAdviseSink
 160
 161 DECLARE_INTERFACE_(IAppAdviseSink, IUnknown)
 162 {
 163     //
 164     // IUnknown methods
 165     //
 166     DECLARE_UNKNOWN_PURE();
 167
 168     //
 169     // This is called to determine the revision of the sink interface
 170     //
 171     STDMETHOD_(short, GetVersion)(THIS) PURE;
 172
 173     //
 174     // This is called when the application exits (return non-zero to block)
 175     //
 176     STDMETHOD (OnQueryQuit)(THIS) PURE;
 177
 178     //
 179     // This is called when the application exits
 180     //
 181     STDMETHOD_(void, OnQuit)(THIS) PURE;
 182
 183     //
 184     // This is called when making an emergency exit
 185     //
 186     STDMETHOD_(void, OnCriticalError)(THIS_ int errorCode) PURE;
 187
 188     //
 189     // This is called when a command is issued (menus, for example)
 190     //
 191     STDMETHOD_(void, OnCommand)(THIS_ unsigned nCmdId) PURE;
 192 };
 193
 194 ///////////////////////////////////////
 195
 196 #define IAppAdviseSink_QueryInterface(p, a, b)  COMQueryInterface(p, a, b)
 197 #define IAppAdviseSink_AddRef(p)                COMAddRef(p)
 198 #define IAppAdviseSink_Release(p)               COMRelease(p)
 199 #define IAppAdviseSink_GetVersion(p)            COMCall0(p, GetVersion)
 200 #define IAppAdviseSink_OnQueryQuit(p)           COMCall0(p, OnQueryQuit)
 201 #define IAppAdviseSink_OnQuit(p)                COMCall0(p, OnQuit)
 202 #define IAppAdviseSink_OnCriticalError(p, a)    COMCall1(p, OnCriticalError, a)
 203
 204 ///////////////////////////////////////////////////////////////////////////////
 205
 206 #endif /* __APPAPI_H */