EDS_DB_schema.h File Reference
Event handler configuration schema.
More...
Detailed Description
Event handler configuration schema.
- Author:
- S.Maldonado
russell@slac.stanford.edu
CVS $Id: EDS_DB_schema.h,v 1.6 2007/10/10 16:27:31 russell Exp $
- Overview
- This schema is meant to be included as part of each individual' handler's configuration. A high level service will access a list of of schema's, which, among other things, will include this schema.
- What It Does
- This schema provides a reference, in the form of the name' to a routine that, when called, will return a pointer to the construction services for this handler. In turn, the construction services structure, contains two routines
- A sizing routine
- A construction routine
- The size routine is returns the amount of memory needed to contain the control and configuration information for this handler. The caller is expected to allocate this amount of memory and then call the the construction routine which will initialize this memory with the control and configuration information.
- About the Arguments
- Both the size and the construction routines are pased two parameters, a pointer to the what is usually the defining schema for this particular handler and an arbitrary parameter. The routines work by examining information from the schema and the user parameter. While, in principle, these two arguments could be collapsed to a single arguments, it is convenient to think of the schema as coming from a more or less static source, for example a file, and prm, representing a set of modifying parameters, coming from a more dynamic source, for example, command line options.
- A Word of Caution
- The amount of memory the amount of memory needed by the construct service must be greater than or equal to that allocated by the size service. Although there are many ways to achieve this, the recommended methdo is to the identical schema and user parameter to both the size and construction routines.
Typedef Documentation
| const EDS_fwHandlerServicesX1(* EDS_DB_handlerConstructRtn)(void *ctl, unsigned int handler_id, const void *schema, unsigned int schema_key, void *prm, EDS_fw *edsFw) |
Signature for a routine to construct an event handler.
- Returns:
- A pointer to the EDS_fwServices structure. This is a vector of routines, defined in EDS, that constains all the information needed to register an event handler
- Parameters:
-
| ctl | The event handler's control block to construct |
| handler_id | The identifier of the handler. This is meant to uniquely identify this handler. Since it is used as the basis to associate other pieces of information with this handler, it should be fixed. |
| schema | The database schema, containing the information needed to construct (i.e. all the parameters) ctl |
| schema_key | The schema key, likely from CDM_getKey |
| prm | A user provided parameter that is meant to possibly modify the parameters in the database schema. In this sense, it represents a more dynamic parameterization of the event handler's configuration. |
| edsFw | Pointer to the EDS framework |
- Usage
- This routine initializes ctl with the control and configuration information for this instance of the handler. This amount of memory in ctl is assumed to be large enough. The recommended method of achieving this is provide a size service, which is passed the same schema and par arguments to calculate the necessary size. The caller then allocates this amount of memory then calls the construction service routine with these same parameters. By passing the same schema and prm arguments, the size and construct routines can agree on the amount of memory needed.
Signature for a routine to get a handler construct services block.
Typedef for struct _EDS_DB_HandlerConstructServices.
(*EDS_DB_handlerServicesGet) (void *prm);
- Returns:
- A pointer to the construction services
- Parameters:
-
| prm | Arbitrary user context parameter. This parameter may be used to determine which vector of services are returned. This same parameter must be passed into the size and construct routines |
- This routine returns are pointer to the construction services structure. This structure contains two callback functions, one to get the sizeof of the structure needed to hold the control and configuration information about this handler and one to construct this information.
Signature for a routine to get event handler's context/control block size (in bytes).
- Returns:
- The size, in bytes, of the event handler's context/control block.
- Parameters:
-
| schema | The database schema for this handler |
| prm | Arbitrary user parameter passed to the this routine and the construct routine. This same value was also passed to the get routine. It may be used to select different configurations. |
- This routine is sizes the structure needed to hold the control and configuration information. The caller is expected to allocate this memory and pass a pointer to the allocated memory into the construction service.
- In general, the size of the control structure is a fixed size, defined by the specific handler, while the configuration size is determined by a combination of specific handler information (for example, the size of one configuration block) and the schema and prm arguments (which may define multiple configuration blocks that are selectable at run-time).
- Note:
- The construction routine assumes that enough memory has been allocated in the control parameter to be filled to hold all the information. The recommended method of achieving this is to pass the identical schema and prm arguments to the construction service.
Typedef for struct _EDS_DB_Schema.
- In order to maintain a strict heirarchy in the package structure, DB files are not allowed to refer to their parent packages. This means that the routine to fetch the construction services, which will live in that parent package, cannot be directly referenced. Therefore, it is indirectly referenced by name. This name is feed to CMX_lookupSymbol, thus resolving the routine's address at runtime. This is a bit hookey but the alternatives (another package just to hold the construct service routines) seem even worse. What one wants is a weak symbol, but this is not supported by the VxWork's dynamic linker.
