SquawkBox Weather Plug-ins

Weather plug-ins can be used to extend the weather functionality of SquawkBox. Weather plug-ins are DLL files that reside in the weather subdirectory of the main SquawkBox program directory. The DLLs must implement and export a number of functions which are described below. This guide assumes that you have an understanding of programming sufficient to create the DLLs.

The Weather Plug-in Header File

Download this header file and include it in your DLL project. This header contains the definitions of functions you will need to implement in your plug-in. This header file is appropriate for inclusion in C or C++ code.

The DLL must implement and export the following functions:
WXInitialize
WXCleanup
FSDConnect
FSDDisconnect
GetPluginName
GetPluginDescription
GetPluginWebsite
GetDataFormatPreference
UpdateWeatherFSDData
UpdateWeatherMETAR
ClearAllWeather

Weather plug-ins can operate in one of two modes: FSD Data mode or METAR mode. The difference between these is in the format of the weather data received from SquawkBox. FSD Data mode sends weather data for a single station for wind, cloud, temperature and pressure. METAR mode sends raw METAR strings for multiple stations in the pilot's vicinity. The mode of the plug-in is determined based on what the plug-in returns from the GetDataFormatPreference function. Only one of UpdateWeatherFSDData and UpdateWeatherMETAR must be implemented, depending on the plug-in mode.

Function Descriptions

The following is a detailed description of how each function should be implemented:

void* fnWXInitialize( )
This function is called when the weather plug-in is first loaded. The plug-in should do all global initialization here. The value returned from this function will be passed to all other functions called for this plugin.

void WXCleanup( void* pContext )
This function is called when the weather plug-in is no longer needed and SquawkBox is about to exit. The plug-in should do all global cleanup here.

void FSDConnect( void* pContext, int version, fnFSUIPCRead* pFSUIPCRead, fnFSUIPCWrite* pFSUIPCWrite )
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 computer, i.e. Flight Simulator is running and has a valid FSUIPC interface available. No weather update requests will come before this function is called. 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 two function pointers passed in should be used to perform FSUIPC read and write operations as the plug-in needs. FSUIPC operations should only be performed by the plugin between calls to FSDConnect and FSDDisconnect. Note that there is no need for the plug-in itself to initialize or cleanup FSUIPC itself. SquawkBox takes care of that so that the read and write functions can be used right away after FSDConnect is called.

void FSDDisconnect( void* pContext )
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.

void GetPluginName( void* pContext, char* name, int size )
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. This is the name that SquawkBox will display in the list of weather providers in the Weather Options dialog.

void GetPluginDescription( void* pContext, char* desc, int size )
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.

void GetPluginWebsite( void* pContext, char* url, int size )
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 the user selects your weather plug-in in the Weather Options dialog and then clicks on the Visit Website button this is the URL their browser will open into. 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.

int GetDataFormatPreference( )
This function indicates the format your plug-in can receive weather data in. You should return one of the SBWX_UI_* IDs listed in the header file.

void UpdateWeatherFSDData( void* pContext, const FSDWeatherData* pData )
This function is called to pass FSD format weather data to the weather plug-in. The plug-in should update the weather in this function. Details of the FSDWeatherData structure can be found in the header file.

void UpdateWeatherMETAR( void* pContext, const char* pMETARs )
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. The plug-in should update the weather in this function.

void ClearAllWeather( void* pContext )
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). The exact definition of "clear" weather is defined by the plug-in.

Note on METAR Mode

As of the release date of SquawkBox 3, the only weather plug-in in existence was the default one that installs with SquawkBox. That plug-in runs in FSD Data mode. As such the current version of SquawkBox does not fully support METAR mode plug-ins. If you are interested in authoring a plug-in that operates in this mode, contact the SquawkBox author directly to get more information and arrange to get a build of SquawkBox that will offer preliminary support for this mode.

Need Help?

Are there parts of this document that are unclear? Do you have questions? Are you having trouble getting your weather plug-in to work properly? For help use the SquawkBox Forum. The forum entitled "SquawkBox Plug-ins" is the best place for these types of questions.