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;


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;


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;


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.