Smart CODE
Your on-line guide to the generated code

NAME
Data Structures and Files

This page describes the various data structures generated as part of Smart Code, and details how they are used in the generated code, as well as their public programming API.

INTRODUCTION
Smart Code can be customized from within X-Designer. Groups can be changed, group elements can be added and deleted. Customizer properties for network connection, and handler routines can be modified.

Most of these changes are handled through the smart code data structure. In C, this is passed into the callout routine as an argument. In C++ and Java it is the base class of the callout class whose doit() method is invoked from a toolkit callback.

Since the Smart Code data object manages the customizations made from within X-Designer, only the X-Designer code file, the stubs file the group code files in the groups_<c|cpp|java>, and the smart code header file are overwritten each time code is generated. All other smart code files are only regenerated if they have been removed, and do not have to be rebuilt each time a customization has been modified.

The Smart Code data structure is designed to work across the possible permutations of language and toolkits available. The data structure has a C, C++ and Java format, and works with X/Motif callbacks, Windows/MFC message handlers and Java/AWT event handlers.

With Get/Set Smart Code, you should program the callout as you would a raw callback or event handler, except that the user interface controls are accessd and modified through toolkit independent group getters and setters rather than through the toolkit API.

For Internet and Thin-Client smart code, the callout is ready written and provides the networking functionality. This callout has hooks for calling user-defined precondition/postcondition routines, and for overriding the routines which send data to, and receive data from the server.

SYNOPSIS
Most of the fields in the C data structure, or the members of the C++ and Java classes are private and are not documented here. These are used in the X-Designer code file to configure your smart code - for example, there are function pointers for the send, receive and out-of-band handler routines set up in the Customiser; there is also a transport member - itself an object with chat() methods to allow the callout to connect across the internet.

Public fields/members are the parts of the data object that are intended for programming within user callouts and handlers. These are:

  • (Callback) Name
  • Group
  • Client-data
  • Poll Interval (Thin Client and Internet only)
  • The data structures below include only PUBLIC elements.

    In the definitions below, GROUPNAME is the name assigned to a particular group, GROUPCLASS is the name of the group class in the generated code, and CALLOUTCLASS is the name of the class that corresponds to a particular callout.

    Get/Set Smart Code

    For Get/Set Smart Code the data fields/methods are intend to be used directly by the programmer in user-defined callouts (or doit methods in classes) in the callouts_<c|cpp|java> directory.

    C
    
    
    typedef struct {
    	char       *            name;
    	AnyGroup_t *            group;
    	void *                  client_data;
    	[.. and private elements]
    } sc_data_t;
    
    Used in the callout:
    
    typedef void (*UserCallbackProc)( sc_data_t *, GROUPNAME_t*, void *)
    
    
    C++
    
    
    class sc_data_c {
    	public:
    		char       * getName();
    		sc_group_c * getGroup();
    		void       * getClientData();
    		void         warn( char * s);
    
    		virtual void doit() = 0;
    	[.. and private elements]
    };
    
    Used in the callout:
    
    class CALLOUTCLASS: public sc_data_c
    {
    	void doit() {
    		GROUPCLASS * g = (GROUPCLASS*)getGroup();
    	}
    };
    
    Java
    
    
    package utils_java;
    
    public abstract class SCData  {
    
    	public String  getName() ...
    	public SCGroup getGroup() ...
    	public Object getClientData() ...
    
    	public abstract void doit() ;
    }
    
    Used in the callout:
    
    package callouts_java;
    
    public class CALLOUTCLASS extends SCData
    {
    	public void doit() {
    		GROUPCLASS g = (GROUPCLASS)getGroup();
    	}
    }
    

    Thin-Client and Internet Smart Code

    For Thin-Client and Internet Smart Code, the data structure/class is used by a ready written doit() routine/method that checks user preconditions/postconditions, connects to a remote server and uses default Send, Receive and Out of Band routines for managing the data transfer to and from the server, unless the programmer has overriden these routines. The default Send and Receive routines for Thin Client serialize, send, deserialize and update the interface and would only be overriden in special circumstances. For Internet Smart Code, the programmer will always provide a Receive routine to manage the data returned from the web. If a Send routine is provided, data sent is POST'ed to the web server. By default, Internet Smart Code uses the GET method.

    C
    
    
    Client Side
    
    typedef struct {
    	char       *            name;
    	AnyGroup_t *            group;
    	void *                  client_data;
    	int                     poll;
    	[.. and private elements]
    } sc_stdcs_t;
    
    Used in the (generated) callout, and:
    
    typedef int (*ReceiveHandlerProc)( sc_stdcs_t*, sc_idata_t*)
    
    typedef int (*SendHandlerProc) ( URLConnection *,sc_stdcs_t *)
    
    typedef int (*OutOfBandHandlerProc)( sc_stdcs_t*, sc_idata_t*)
    
    Server Side
    
    typedef struct  {
    	char *       name;
    	AnyGroup_t * group;
    	int          poll;
    } sc_data_t;
    
    Used in the callout:
    
    
    C++
    
    
    Client Side
    
    class sc_stdcs_c: public sc_data_c
    {
    	public:
    		virtual int preconditions()  = 0;
    		virtual int postconditions() = 0;
    
    		void setPollInterval( int seconds);
    		int getPollInterval();
    		void doit();
    
    	[.. and private elements]
    
    	// and inherited methods:
    		char       * getName();
    		sc_group_c * getGroup();
    		void       * getClientData();
    		void         warn( char * s);
    };
    
    Used in the (generated) callout:
    
    class CALLOUTCLASS: public sc_stdcs_c
    {
    	int preconditions()  { return 1; }
    	int postconditions() { return 1; }
    };
    
    And in:
    
    typedef int (*ReceiveHandlerProc)( sc_stdcs_c*, sc_idata_c*)
    
    typedef int (*SendHandlerProc) ( URLConnection *,sc_stdcs_c *)
    
    typedef int (*OutOfBandHandlerProc)( sc_stdcs_c*, sc_idata_c*)
    
    Server Side
    
    class sc_data_c {
    	public:
    		char       * getName();
    		sc_group_c * getGroup();
    
    		void setPoll(  int p);
    		int  getPoll();
    
    		virtual int doit() = 0;
    };
    
    class CALLOUTCLASS: public sc_data_c
    {
    	public:
    		int doit();
    
    		static CALLOUTCLASS * new_doit_callback_c();
    
    		GROUPCLASS * getGroup();
    };
    
    int
    CALLOUTCLASS::doit  ()
    {
    	GROUPCLASS * g = getGroup();
    
    	return 1;
    }
    
    
    Java
    
    
    Client Side
    
    package utils_java;
    
    public abstract class SCStdCS extends SCData
    {
    	public abstract boolean preconditions();
    	public abstract boolean postconditions();
    
    	public void setPollInterval( int seconds) ...
    	public int getPollInterval() ...
    
    	public void doit() ...
    }
    
    Used in the (generated) callout:
    
    package callouts_java;
    
    public class CALLOUTCLASS extends SCStdCS
    {
    	public boolean preconditions()  { return true; }
    	public boolean postconditions() { return true; }
    }
    
    And in:
    
    public class ReceiveHandlerClass extends SCInputDataHandler
    
    public class SendHandlerClass extends SCOutputDataHandler
    
    public class OutOfBandHandlerClass extends SCInputDataHandler
    
    NB. use C or C++ Server Side code
    

    DESCRIPTION
    The Get/Set data structure/class is considerably simpler than the client-server structures. However, their public interface is extended only with the PollInterval getters and setters, which are used by the client to poll the server asychronously.

    Name
    is the name of the callback/method associated with the data structure. For Get/Set this is useful if you are using a single callout to service a number of user-interface callbacks and need to differentiate between them. For Thin-Client and Internet, the Name is used on the server side to lookup which server-side callout needs to be invoked for an incoming request.

    Group
    - the Group field/method is used to access the group object associated with the callout. Since the group object makes all toolkit-independant getters and setters available to the callout, the code to provide a local handle on the group is generated as part of the callout stub.

    Client Data
    is currently only available for C functions, and corresponds to the client-data field in Xt callbacks. It allows you to pass arbitrary extra data into the callout. In C++ and Java you would provide getter and setter routines for your user data within your callout class.

    Poll Interval
    is only used in Thin-Client Smart Code, and controls the timing of asychronous polling of the server by the client. This is akin to the REFRESH meta command in the head of an HTML document, allowing client-driven push like facilities. It is intended that the server itself sets the poll interval using the poll field or the setPoll() method - but the API allows the client to override this request.

    Instances of Data Objects
    - by default, each callout has its own instance of each and every data structure. Callouts can share smart code data structures if the programmer modifies the GetNew...() routines to return existing data rather than new instances.

    The warn method
    C++ diagnostics are handled through the warn method. The default warn method on Unix writes to the standard diagnostic. On Windows, calls to warn() display the information through an AfxMessageBox() call.

    Server-side Data Objects
    Server side data objects allow access to the group and setting of the poll-interval through the poll field or the setPoll/getPoll methods. The data architecture is the same as on the client side, where in C, the data object is passed into the callout, while in C++ and Java the data object is subclassed, and the user-defined doit() method is called.

    preconditions/postconditions and the ready written Internet callout
    The generated callout for Thin-Client and Internet programming follows the sequence:

  • Call the user preconditions() routine. If it fails (returns zero in C, C++) abandon the callout.
  • If the Server Push customization has been chosen, call the trasnport object's asychronous chat() routine, and return.
  • Otherwise call the transport object's chat() routine. This returns an Internet Data object.
  • Call the continuation routine receive() to process this data.
  • The asynchronous chat() also calls the receive() continuation routine each time it connects to the server.

    The receive routine follows the sequence:

  • If there is no data, return.
  • If the user has supplied a Receive Handler, call it, tidy up afterwards and return.
  • If the MIME type of the returned data does not correspond to the private MIME type expected by the Thin-Client code, call the user's Out of Band Handler if one has been supplied, otherwise call the default handler which outputs the data to the standard diagnostic.
  • Load the data into the group object
  • Call the user's postconditions() handler, to allow the application to check the updated values for the group controls. If it fails (returns zero in C, C++), abandon the callout.
  • Update the interface as requested by the server.
  • USAGE
    The Smart Code data structures/methods are intended to be created by X-Designer in the code that is generated to prime callbacks. For this reason, getter methods are defined as public in the SYNOPSIS above, while setter methods are only documented for the Poll Interval.

    Send Handlers are called with the Smart Code Data Object, allowing access to the group object etc, and a URLConnection object for updating the URL's content headers and for writing data to the URL's OutputStream.

    Receive Handlers and Out of Band Data Handlers are called with the Smart Code Data Object and the Internet Data Object, which gives access to the URL's MIME Type, and its returning InputStream.

    EXAMPLES
    Examples of setting up smart code data structures can be found in the X-Designer main code file, where Smart Code callbacks are set up on individual controls. Example code is also generated in comments within callouts and Send/Receive handlers. Live example code can be produced by running the Smart Code replay scripts, which produce an interface, and generate working callouts. Finally, use of the GoLive! @ notation in the Thin-Client and Internet customizer will cause live code to be generated that will update/read from the control.

    SEE ALSO
    Group Objects, Internet Data, URLConnection, InputStream and OutputStream Send Handlers, Receive Handlers, Out of Band Data Handlers