GNOME CORBA Framework
<<< Previous Page | Home | Up |

# goad

## Name

goad -- GNOME Object Activation Directory

## Synopsis

    const char* goad_server_activation_id       (void);
    int         goad_server_register            (CORBA_Object name_server,
                                                 CORBA_Object server,
                                                 const char *name,
                                                 const char *kind,
                                                 CORBA_Environment *ev);
    int         goad_server_unregister          (CORBA_Object name_server,
                                                 const char *name,
                                                 const char *kind,
                                                 CORBA_Environment *ev);
    enum        GoadServerType;
    enum        GoadActivationFlags;
    struct      GoadServer;
    struct      GoadServerList;
    GoadServerList* goad_server_list_get        (void);
    void        goad_server_list_free           (GoadServerList *server_list);
    CORBA_Object goad_server_activate           (GoadServer *sinfo,
                                                 GoadActivationFlags flags,
                                                 const char **params);
    CORBA_Object goad_server_activate_with_repo_id
                                                (GoadServerList *server_list,
                                                 const char *repo_id,
                                                 GoadActivationFlags flags,
                                                 const char **params);
    CORBA_Object goad_server_activate_with_id   (GoadServerList *server_list,
                                                 const char *server_id,
                                                 GoadActivationFlags flags,
                                                 const char **params);

## Description

GOAD is the GNOME Object Activation Directory. It keeps track of the CORBA object implementations available on the system, and allows applications to activate these implementations or access currently running ones.

## Details

### goad_server_activation_id ()

    const char* goad_server_activation_id       (void);

When an application that implements a GOAD-registered object is started, it should call this function to check if it was started to create one of those objects.

Returns : | the GOAD ID that the program was executed to make available.

### goad_server_register ()

    int         goad_server_register            (CORBA_Object name_server,
                                                 CORBA_Object server,
                                                 const char *name,
                                                 const char *kind,
                                                 CORBA_Environment *ev);

Registers `server` in the `name_server` with `name`.

`name_server` : | points to a running name_server
`server` : | the server object we want to register.
`name` : | The GOAD id of the server that is being registered
`kind` : | "object" for now.
`ev` : | CORBA_Environment to return errors
Returns : | zero upon success, non-zero if registration failed or another registration for this name already exists.

### goad_server_unregister ()

    int         goad_server_unregister          (CORBA_Object name_server,
                                                 const char *name,
                                                 const char *kind,
                                                 CORBA_Environment *ev);

Removes the registration of `server` in the `name_server`.

`name_server` : | points to a running name_server
`name` : | The GOAD ID of the server we want to remove from the name server registration.
`kind` : | "object" for normal use.
`ev` : | CORBA_Environment to return errors
Returns : | zero upon success, non-zero on error.

### enum GoadServerType

    typedef enum {
    	GOAD_SERVER_SHLIB = 1,
    	GOAD_SERVER_EXE = 2,
    	GOAD_SERVER_RELAY = 3,
    	GOAD_SERVER_FACTORY = 4
    } GoadServerType;

- GOAD_SERVER_SHLIB - implementation is in a shared library plugin

- GOAD_SERVER_EXE - implementation is in a separate program

- GOAD_SERVER_RELAY - implementation is accessable via a relay object (not yet implemented)

- GOAD_SERVER_FACTORY - implementation is started by talking to a GNOME::GenericFactory object

### enum GoadActivationFlags

    typedef enum {
    	/* these two are mutually exclusive */
    	GOAD_ACTIVATE_SHLIB = 1 << 0, 	/* prefer shlib activation */
    	GOAD_ACTIVATE_REMOTE = 1 << 1, 	/* prefer remote activation */

    	/* these two are mutually exclusive */
    	GOAD_ACTIVATE_EXISTING_ONLY = 1 << 2, /* Only do lookup in name
    					       * service for currently running
    					       * version.
    					       */
    	GOAD_ACTIVATE_NEW_ONLY = 1 << 3,      /* No lookup in name service. */
    	GOAD_ACTIVATE_ASYNC = 1 << 4 /* Just make sure that the object is running */
    } GoadActivationFlags;

- GOAD_ACTIVATE_SHLIB - indicates activation from a shared library plugin is preferred

- GOAD_ACTIVATE_REMOTE - indicates activation from an executable or factory is preferred

- GOAD_ACTIVATE_EXISTING_ONLY - Don't create a new object, simply access the currently running implementation if available.

- GOAD_ACTIVATE_NEW_ONLY - Don't look for a currently running implementation, just create a new one (mutually exclusive with GOAD_ACTIVATE_EXISTING_ONLY)

- GOAD_ACTIVATE_ASYNC - just start the object implementation, but don't worry about getting a reference to it.

### struct GoadServer

    typedef struct {
    	GoadServerType type;
            GoadActivationFlags flags; /* only GOAD_ACTIVATE_NEW_ONLY
    				      currently parsed in */
    	char     **repo_id;
    	char     *server_id;
    	char     *description;

            /*
    	 * Executable/shlib path, relayer IOR, whatever.
    	 * This field may disappear at any time. You have been warned ;-)
    	 */
    	char     *location_info;
    } GoadServer;

- 'type' - The GoadServerType of the implementation being listed

- 'flags' - The bitwise OR of all the GoadActivationFlags that are enforced for this GoadServer

- 'repo_id' - An array of strings giving all the interfaces supported by this implementation

- 'server_id' - The GOAD ID of this implementation. A GOAD ID is a unique global identifier of a particular object implementation.

- 'description' - A human-readable description of this object, if applicable

- 'location_info' - Information on how to activate the object. The meaning varies depending on the 'type'

### struct GoadServerList

    typedef struct {
      GoadServer *list;
      GHashTable *by_goad_id;
    } GoadServerList;

'list' is an array of GoadServer structures. 'by_goad_id' is a hash table with the GOAD ID of each implementation as the key, and the GoadServer structure for that implementation as the value.

### goad_server_list_get ()

    GoadServerList* goad_server_list_get        (void);

Returns an array listing all the servers available for activation.

Returns : | a newly created server list.

### goad_server_list_free ()

    void        goad_server_list_free           (GoadServerList *server_list);

Frees up all the memory associated with `server_list` (which should have been received from goad_server_list_get())

Side effects: Invalidates the memory pointed to by 'server_list'.

`server_list` : | a GoadServerList structure.

### goad_server_activate ()

    CORBA_Object goad_server_activate           (GoadServer *sinfo,
                                                 GoadActivationFlags flags,
                                                 const char **params);

Activates a CORBA server specified by 'sinfo', using the 'flags' hints on how to activate that server.

`sinfo` : | information on the server to be "activated"
`flags` : | information on how the application wants the server to be activated.
`params` : | Pass NULL here for normal applications.
Returns : | a CORBA_Object that points to this server, or CORBA_OBJECT_NIL if the activation failed.

### goad_server_activate_with_repo_id ()

    CORBA_Object goad_server_activate_with_repo_id
                                                (GoadServerList *server_list,
                                                 const char *repo_id,
                                                 GoadActivationFlags flags,
                                                 const char **params);

Activates a CORBA server specified by 'repo_id', using the 'flags' hints on how to activate that server. Picks the first one on the list that meets criteria.

This is done by possibly making three passes through the list, the first pass checking for existing objects only, the second pass taking into account any activation method preferences, and the last pass just doing "best we can get" service.

`server_list` : | a server listing returned by goad_server_list_get. If NULL, we will call the function ourself and use that.
`repo_id` : | the repository ID of the interface that we want to activate a server for.
`flags` : | information on how the application wants the server to be activated.
`params` : | NULL for normal applications.
Returns : | the activated object.

### goad_server_activate_with_id ()

    CORBA_Object goad_server_activate_with_id   (GoadServerList *server_list,
                                                 const char *server_id,
                                                 GoadActivationFlags flags,
                                                 const char **params);

Activates a CORBA server specified by 'repo_id', using the 'flags' hints on how to activate that server. Picks the first one on the list that matches.

`server_list` : | a server listing returned by goad_server_list_get. If NULL, we will call that function ourself and use that.
`server_id` : | the GOAD ID of the server that we want to activate.
`flags` : | information on how the application wants the server to be activated.
`params` : | NULL for now.
Returns : | the newly activated object.

<<< Previous Page | Home | Up |
gnorba |