Dynamic symbols

These functions can be used to dynamically access symbols exported by the plug-ins. More...

Functions
CP_IMPORT cp_status_t	cp_define_symbol (cp_context_t *ctx, const char *name, void *ptr)
	Defines a context specific symbol. More...
CP_IMPORT void *	cp_resolve_symbol (cp_context_t *ctx, const char *id, const char *name, cp_status_t *status)
	Resolves a symbol provided by the specified plug-in. More...
CP_IMPORT void	cp_release_symbol (cp_context_t *ctx, const void *ptr)
	Releases a previously obtained symbol. More...

Detailed Description

These functions can be used to dynamically access symbols exported by the plug-ins.

They are intended to be used by a plug-in runtime or by the main program.

Function Documentation

cp_define_symbol()

CP_IMPORT cp_status_t cp_define_symbol	(	cp_context_t *	ctx,
		const char *	name,
		void *	ptr
	)

Defines a context specific symbol.

If a plug-in has symbols which have a plug-in instance specific value then the plug-in should define those symbols when it is started. The defined symbols are cleared automatically when the plug-in instance is stopped. Symbols can not be redefined.

Parameters

ctx	the plug-in context
name	the name of the symbol
ptr	pointer value for the symbol

Returns

CP_OK (zero) on success or a status code on failure

cp_resolve_symbol()

CP_IMPORT void* cp_resolve_symbol	(	cp_context_t *	ctx,
		const char *	id,
		const char *	name,
		cp_status_t *	status
	)

Resolves a symbol provided by the specified plug-in.

The plug-in is started automatically if it is not already active. The symbol may be context specific or global. The framework first looks for a context specific symbol and then falls back to resolving a global symbol exported by the plug-in runtime library. The symbol can be released using cp_release_symbol when it is not needed anymore. Pointers obtained from this function must not be passed on to other plug-ins or the main program.

When a plug-in runtime calls this function the plug-in framework creates a dynamic dependency from the symbol using plug-in to the symbol defining plug-in. The symbol using plug-in is stopped automatically if the symbol defining plug-in is about to be stopped. If the symbol using plug-in does not explicitly release the symbol then it is automatically released after a call to the stop function. It is not safe to refer to a dynamically resolved symbol in the stop function except to release it using cp_release_symbol.

When the main program calls this function it is the responsibility of the main program to always release the symbol before the symbol defining plug-in is stopped. It is a fatal error if the symbol is not released before the symbol defining plug-in is stopped.

Parameters

ctx	the plug-in context
id	the identifier of the symbol defining plug-in
name	the name of the symbol
status	a pointer to the location where the status code is to be stored, or NULL

Returns

the pointer associated with the symbol or NULL on failure

cp_release_symbol()

CP_IMPORT void cp_release_symbol	(	cp_context_t *	ctx,
		const void *	ptr
	)

Releases a previously obtained symbol.

The pointer must not be used after the symbol has been released. The symbol is released only after as many calls to this function as there have been for cp_resolve_symbol for the same plug-in and symbol.

Parameters

ctx	the plug-in context
ptr	the pointer associated with the symbol