GPI Serialization

A GPI can store data in the ShapeUp workspace file (*.sup) when the user chooses to save the workspace. Data can be saved on workspace basis, and/or on theme basis. When such a workspace is later loaded, the stored data is sent to the plug-in to be parsed and used.

E.g. if a plug-in draws extra data on top of the map, the settings for how this is drawn can be stored in the workspace file and reused when that workspace is reopened.

Note:
A plug-in can set the data to be serialized at almost any time. The only time it's not permitted is during the loading process.
A sample of how to store data:
{
    struct MyData
    {
        int version;
        double precision;
    } data;

    const char *string_data = "Some data";

    // Store data on workspace level
    SUWorkspace workspace(hWorkspace);
    workspace.SetSerialData(sizeof(MyData), &data);

    // Store data on theme level
    SUTheme theme(hTheme);
    theme.SetSerialData(strlen(string_data) + 1, string_data);
}

In order to reserialize data stored, a hook funktion needs to be used, ShapeUp_AddDeserializeHook(), which enables a call to the GPI hook function when a loading operation occurrs.

A sample of the deserialize hook functionality might look like:

SURESULT __cdecl fnInit(SUExport *pExport)
{
    ...
    // Set hook function
    pExport->import.pfnHook = MyHookFunc;

    // Set-up our loading hook
    ShapeUp_AddDeserializeHook(0);
    ...
}

SURESULT __cdecl MyHookFunc(SUHANDLE hWorkspace, int hookType, SUHookData *args)
{
    switch (hookType)
    {
    case HOOKTYPE_DESERIALIZE:
        {
            // args is really a pointer to a SUDeserializeHookData struct
            SUDeserializeHookData *data = (SUDeserializeHookData*) args;

            // If data->hTheme == NULL we are loading a workspace, otherwise
            // we are loading the theme pointed to by data->hTheme

            if (data->hTheme == NULL)
                LoadWorkspaceData(hWorkspace, data);
            else
                LoadThemeData(hWorkspace, data);
        }
        break;
    default:
        break;
    }
    return SURESULT_OK;
}
Warning:
Do not assume that the workspace hWorkspace in the hook function will point to the workspace containing the currently loading theme. I.e. if the user is loading themes from a workspace using the Insert | Add Themes from Workspace command, the hWorkspace will point to the active workspace rather than the workspace that contains the themes to be extracted. In this case, any serialized workspace based data in the loading workspace file will remain unread. This means you cannot store data for a theme that is depending on data stored for its workspace.
See also:
ShapeUp_AddDeserializeHook(), FNTYPE_WORKSPACE_SETSERIALDATA, FNTYPE_THEME_SETSERIALDATA, HOOKTYPE_DESERIALIZE
Make sure you have first read the introduction.
Generated on Thu Apr 15 10:55:34 2010 for ShapeUp API by  doxygen 1.5.2