//
// This is the interface for writing Weather Plug-ins for SquawkBox 3.
//
// To create a weather plug-in you must create a DLL and export several
// functions, as outlined below.  The DLL must be placed in the 'weather'
// subdirectory below the main SquawkBox program directory.  When this
// happens your weather plug-in will be selectable by the user in the weather
// options dialog.  If your plug-in is selected as the weather provider,
// SquawkBox will call you whenever a weather update is needed.
//
// The list of functions you must implement and export are:
//   WXInitialize
//   WXCleanup
//   FSDConnect
//   FSDDisconnect
//   GetPluginName
//   GetPluginDescription
//   GetPluginWebsite
//   GetDataFormatPreference
//   UpdateWeatherFSDData OR UpdateWeatherMETAR (only one required)
//   ClearAllWeather
//

#ifndef SBWX_H_
#define SBWX_H_


#ifdef __cplusplus
extern "C"
{
#endif


// These functions are provided to each plug-in so that it can perform FSUIPC
// operations.  FSUIPC initialization is handled completely by SquawkBox.
// These functions exactly mirror the functions in the FSUIPC SDK.
//
typedef BOOL __cdecl fnFSUIPCRead( DWORD dwOffset, DWORD dwSize, void *pDest );
typedef BOOL __cdecl fnFSUIPCWrite( DWORD dwOffset, DWORD dwSize, void *pSrce );


//
// [ Startup and Shutdown Functions ]
//
// These functions are called to allow the weather plug-in to initialize itself
// and to clean up just before SquawkBox exits.
//

// Function Name: WXInitialize
// This function is called when the weather plug-in is first loaded.  The value
// returned from this function will be passed to all other functions called for
// this plugin.
//
typedef void* fnWXInitialize( );

// Function Name: WXCleanup
// This function is called when the weather plug-in is no longer needed and
// SquawkBox is about to exit.
//
typedef void fnWXCleanup( void* pContext );

// Function Name: FSDConnect
// This function is called to notify the plug-in that the user has successfully
// connected to the FSD server.  The plug-in can assume that at this point
// SquawkBox has confirmed the presence of an FSUIPC interface on the system,
// i.e. Flight Simulator is running and has a valid FSUIPC interface available.
// No weather update requests will come before this function is called, so
// this would be an appropriate time for the plugin to initialize its
// FSUIPC connection.  The version number passed in indicates the version of
// Flight Simulator that the user is running.  Currently valid values are:
//   8 = Flight Simulator 2002
//   9 = Flight Simulator 2004
//
// The FSUIPCInterface pointer contains a struct with pointers to functions
// for performing FSUIPC read, writes and processes.  The types of these functions
// are defined above.  FSUIPC operations should only be performed by the plugin
// between calls to FSDConnect and FSDDisconnect.
//
typedef void fnFSDConnect( void* pContext,
                           int version,
                           fnFSUIPCRead* pFSUIPCRead,
                           fnFSUIPCWrite* pFSUIPCWrite );

// Function Name: FSDDisconnect
// This function is called to notify the plug-in that the user has disconnected
// from the FSD server.  No weather update requests will come after this call.
//
typedef void fnFSDDisconnect( void* pContext );





//
// [ General Information Functions ]
// These functions provide SquawkBox with general information about the plug-in.
//

// Function Name: GetPluginName
// This function should fill the supplied buffer with a short name describing
// your plug-in.  The number of characters copied into the buffer should not
// exceed the passed size, including the terminating null character.
//
typedef void fnGetPluginName( void* pContext, char* name, int size );

// Function Name: GetPluginDescription
// This function should fill the supplied buffer with a longer description of
// your plug-in.  This could include author information and copyright information.
// It will be displayed to the user when they select your plug-in in the weather
// options dialog. The number of characters copied into the buffer should not
// exceed the passed size, including the terminating null character.
//
typedef void fnGetPluginDescription( void* pContext, char* desc, int size );

// Function Name: GetPluginWebsite
// This function should fill the supplied buffer with a URL for a web site
// related to your plug-in.  Ensure you use a URL that will continue to work
// for a long time.  If you do not want to provide a URL, simply pass back
// an empty string by putting a null character at the beginning of the supplied
// buffer.  The number of characters copied into the buffer should not
// exceed the passed size, including the terminating null character.
//
typedef void fnGetPluginWebsite( void* pContext, char* url, int size );



//
// [ Data Format Preference ]
//
// This function allows the plug-in to tell SquawkBox the kind of data
// it wants to receive.
//

#define SBWX_DF_FSDNATIVE   0       // Layered cloud, wind and temperature data
                                    // returned by the FSD server
#define SBWX_DF_METAR       1       // Raw METAR strings

// Function Name: GetDataFormatPreference
// This function indicates the format you wish to receive weather data in.
// You should return one of the SBWX_DF_ ids listed above.
// 
typedef int fnGetDataFormatPreference( );



//
// [ Weather Updates ]
//
// These functions are called by SquawkBox when you should update the
// weather.  Only the functions appropriate to the data format your plugin
// indicated in the above function will get called.
//

// These structures are used to hold FSD native weather data
//
struct FSDCloudData
{
    int floor;                       // Floor in feet ASL
    int ceiling;                     // Ceiling in feet ASL
    char octars;                     // Coverage in octars (0 - 8)
    char icing;                      // Non-zero indicates icing
    unsigned char turbulence;        // Turbulence (0 = none, 255 = max)
};
struct FSDWindData
{
    int floor;                       // Floor in feet ASL
    int ceiling;                     // Ceiling in feet ASL
    int direction;                   // Direction in degrees (as reported in the METAR)
    int speed;                       // Speed in knots
    char gusting;                    // Non-zero indicates gusty winds
    unsigned char turbulence;        // Turbulence (0 = none, 255 = max)
};
struct FSDTempData
{
    int ceiling;                     // Ceiling in feet ASL
    char temp;                       // Temp in degrees celsius
};
struct FSDWeatherData
{
    FSDCloudData clouds[ 3 ];        // Layers from lowest to highest
    FSDWindData wind[ 4 ];           // Layers from lowest to highest
    FSDTempData temp[ 4 ];           // Layers from lowest to highest
    int pressure;                    // Presure in inches * 100
    float visibility;                // Visibility in miles
};

// Function Name: UpdateWeatherFSDData
// This function is called to pass FSD format weather data to the weather
// plug-in.  The plug-in should update the weather when it receives this
// message.
//
typedef void fnUpdateWeatherFSDData( void* pContext,
                                     const FSDWeatherData* pData );

// Function Name: UpdateWeatherMETAR
// This function is called to pass METAR data to the weather plug-in.
// The passed text buffer contains all the METARs separated by a null
// character.  The entire buffer ends with two null characters.
// The METARs are listed in the buffer in order of increasing distance
// from the user's current position.
//
typedef void fnUpdateWeatherMETAR( void* pContext,
                                   const char* pMETARs );

// Function Name: ClearAllWeather
// This function is called when the user has requested that all weather
// should be cleared.  The weather plug-in should set the weather to
// a default cleared state (e.g. clear skies, unlimited visibility, no
// wind, etc).
//
typedef void fnClearAllWeather( void* pContext );



#ifdef __cplusplus
}
#endif


#endif