Dynamic symbols
[Functions]

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.


Functions

cp_status_t cp_define_symbol (cp_context_t *ctx, const char *name, void *ptr)
 Defines a context specific symbol.
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.
void cp_release_symbol (cp_context_t *ctx, const void *ptr)
 Releases a previously obtained symbol.

Function Documentation

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

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

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

C-Pluff, a plug-in framework for C
Copyright 2007 Johannes Lehtinen

Generated on Fri Apr 6 15:40:55 2007 for C-Pluff C API by doxygen 1.5.1