time

Agent Software Development Kit

An agent's job is to exchange external data with spreadsheet memory. An AgentSdk is available to allow third parties to extend Data Flask to support additional external formats.

Writing an agent involves creating a class derived from CiExtraAgent (Data Flask was called Extra in development), and implementing it in an afx extension dll, renamed as an exa. Any .exa file placed in the Agent folder below Flask.exe will be automatically be loaded. Three major functions that an agent must overload are DataLoad, DataWrite and OnDataLinkProperties which are called respectively with the Open Data, Write Data, and Data Link commands. Agents may optionally add a tab to the data window.

All exchange of external data by both the OleDb Agent, and the Desktop agent, was done using the AgentSdk. As an experiment, temporarily rename ExtraAgentOleDb.exa to ExtraAgentOleDb.exb. Load Data Flask and notice that the OleDb tab in the Data window is gone. If you load a .dfg that uses the OleDb agent you cannot read or write external data until agent is restored.

Email dataflask@inters.com to request information regarding the Data Flask Agent SDK. Please include a brief description of the type of data that you wish to write an agent for.

To get an idea of some of the details, the following was clipped from the Agent Header:

//ExtraAgent.h
#ifndef EXTRAAGENT_H
#define EXTRAAGENT_H

//An Extra agent controls how data is loaded into, and saved out of a grid. Agents may register file extensions to associate
// themselves with a certain file type. For example, the OleDb Agent registers Access .mdb files. Agents may also provide a
// tab in the agent window to provide a browse and load UI. Finally, agents can override CiExtraCug if they have the Dundas
// Ultimate Grid, allowing agents to customize the grid itself.

//Agents are loaded from Agent (.exa) files. Agent files are MFC extension dynamic link libraries (_AFXEXT). Agent objects are
// created through MFC's CObject runtime class information and must be declared with DECLARE_SERIAL().

//The process for creating an agent is outlined as follows:
// 1. Create an extension DLL project, change name from .DLL to .EXA.
// 2. Add your agent object derived from CiExtraAgent (A CCmdTarget defined through ExtraAgentLib.h). Make it serializable.
// 3. Override GetName, GetDescription for identification.
// 4. Override GetFileExt for file support. Optional.
// 5. Override CreateDataWindow. Optional if GetFileExt provided.
// 6. Override NewDocument and populate prblLink. See 'NewDocument' notes below.
// 7. Override DataLoad and populate prblData and prblCol.
// 8. Override DataWrite to save data (if data is not read-only).
// 9. Provide properties dialogs. Activate within OnFileLinkProperties and OnClickedButtonColumnProperties.
// Details below.

class CiExtraAgent : public CCmdTarget
{
   //Agents must override NewDocument, DataLoad and DataWrite. These three
   // functions are the grid's basic interface to the data. Override CreateDataWindow to add to an optional Agent tab.

   public:
   //Name
   virtual CString GetName(); //Short name for the agent.
   virtual CString GetDescription(); //Description of agent.
   virtual void GetPropDesc(const CiExtraPropDesc **padLink, const CiExtraPropDesc **padTable); //Get description of properties. Override to provide descriptions of link properties.
   //The name stored in the grid file comes fromGetRuntimeClass()->m_lpszClassName.

   //File support
   virtual const char *GetFileFilter(); //File extensions. Same format as CFileDialog::CFileDialog's lpszFilter param (terminating || is optional).
   virtual bool OnFileLinkProperties(const char *sFileName, const char *sTypeAs=NULL, bool *pbBold=NULL); //Associate properties with a filename (m_mapFilenameProp[sDataFileName]). bSet indicates that properties are associated.

   //Data
   virtual bool NewDocument(CDocument *pDoc,
    IRbl *prblLink, //Set link.
    IRbl *prblCols, //Set link related columns.
    //The following parameters are valid for data file associations (GetFileFilter is overridden).
    CString *psFileDataName=NULL, //Data file database name. [out] if a FileName is selected.
    CString *psFileTableName=NULL, //Data file table name (if not implied from filename). [out] if a TableName is selected.
    CString *psFileType=NULL //Open as as specific type (override extension default). [out] if an override type selected.
   )=0; //Data link information. Return false to stop document creation.
   virtual bool DataLoad (CDocument *pDoc,
    IRbl *prblLink, //Provides link to data.
    IRbl *prblData, //The data.
    IRbl *prblCols //Columns. Previous columns provided on reload.
   ); //Read data from your data source. UI Not recommended. Return false if data could not be loaded.
   virtual bool DataWrite (CDocument *pDoc,
    IRbl *prblLink,
    IRbl *prblCols,
    IRbl *prblData
   )=0; //Save data to your data source.

   //User interface
   virtual CWnd* CreateDataWindow(CWnd *pParentWnd, UINT nID); //pParentWnd is the Data docking bar. This function should respond quickly. See notes for notes below.
   CRuntimeClass *m_prtcCug; //Replacable. Grid window class that gets created with the view. CiExtraCug by default. See note at bottom of this file.
   virtual bool OnDataLinkProperties (IRbl *prblLink, IRbl *prblCols, IRbl *prblData); //Override to show a data link properties dialog. See OnDataLinkProperties note below.
};