1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 <html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
3 <title>C-Pluff C API: Dynamic symbols</title>
4 <link href="doxygen.css" rel="stylesheet" type="text/css">
5 <link href="tabs.css" rel="stylesheet" type="text/css">
7 <!-- Generated by Doxygen 1.5.1 -->
10 <li><a href="index.html"><span>Main Page</span></a></li>
11 <li><a href="modules.html"><span>Modules</span></a></li>
12 <li><a href="annotated.html"><span>Data Structures</span></a></li>
13 <li><a href="files.html"><span>Files</span></a></li>
14 <li><a href="pages.html"><span>Related Pages</span></a></li>
16 <h1>Dynamic symbols<br>
18 [<a class="el" href="group__cFuncs.html">Functions</a>]</small>
19 </h1><hr><a name="_details"></a><h2>Detailed Description</h2>
20 These functions can be used to dynamically access symbols exported by the plug-ins.
22 They are intended to be used by a plug-in runtime or by the main program.
24 <table border="0" cellpadding="0" cellspacing="0">
26 <tr><td colspan="2"><br><h2>Functions</h2></td></tr>
27 <tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="el" href="group__cEnums.html#gd6a8106d281ffa4b1f43fe8e3effc7da">cp_status_t</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="group__cFuncsSymbols.html#g9d128b52c0ffe2d4215026fe59f9abeb">cp_define_symbol</a> (<a class="el" href="group__cTypedefsOpaque.html#gcb1aa0619dcefa746383c5e0833b62e7">cp_context_t</a> *ctx, const char *name, void *ptr)</td></tr>
29 <tr><td class="mdescLeft"> </td><td class="mdescRight">Defines a context specific symbol. <a href="#g9d128b52c0ffe2d4215026fe59f9abeb"></a><br></td></tr>
30 <tr><td class="memItemLeft" nowrap align="right" valign="top">void * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__cFuncsSymbols.html#g8bc3b7fcf4f4ed414837f5a3998d46b7">cp_resolve_symbol</a> (<a class="el" href="group__cTypedefsOpaque.html#gcb1aa0619dcefa746383c5e0833b62e7">cp_context_t</a> *ctx, const char *id, const char *name, <a class="el" href="group__cEnums.html#gd6a8106d281ffa4b1f43fe8e3effc7da">cp_status_t</a> *status)</td></tr>
32 <tr><td class="mdescLeft"> </td><td class="mdescRight">Resolves a symbol provided by the specified plug-in. <a href="#g8bc3b7fcf4f4ed414837f5a3998d46b7"></a><br></td></tr>
33 <tr><td class="memItemLeft" nowrap align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="group__cFuncsSymbols.html#g150629125a61ac9fa4e2095b0d9c7e57">cp_release_symbol</a> (<a class="el" href="group__cTypedefsOpaque.html#gcb1aa0619dcefa746383c5e0833b62e7">cp_context_t</a> *ctx, const void *ptr)</td></tr>
35 <tr><td class="mdescLeft"> </td><td class="mdescRight">Releases a previously obtained symbol. <a href="#g150629125a61ac9fa4e2095b0d9c7e57"></a><br></td></tr>
37 <hr><h2>Function Documentation</h2>
38 <a class="anchor" name="g9d128b52c0ffe2d4215026fe59f9abeb"></a><!-- doxytag: member="cpluff.h::cp_define_symbol" ref="g9d128b52c0ffe2d4215026fe59f9abeb" args="(cp_context_t *ctx, const char *name, void *ptr)" -->
40 <div class="memproto">
41 <table class="memname">
43 <td class="memname"><a class="el" href="group__cEnums.html#gd6a8106d281ffa4b1f43fe8e3effc7da">cp_status_t</a> cp_define_symbol </td>
45 <td class="paramtype"><a class="el" href="group__cTypedefsOpaque.html#gcb1aa0619dcefa746383c5e0833b62e7">cp_context_t</a> * </td>
46 <td class="paramname"> <em>ctx</em>, </td>
49 <td class="paramkey"></td>
51 <td class="paramtype">const char * </td>
52 <td class="paramname"> <em>name</em>, </td>
55 <td class="paramkey"></td>
57 <td class="paramtype">void * </td>
58 <td class="paramname"> <em>ptr</em></td><td> </td>
63 <td></td><td></td><td width="100%"></td>
70 Defines a context specific symbol.
72 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.<p>
73 <dl compact><dt><b>Parameters:</b></dt><dd>
74 <table border="0" cellspacing="2" cellpadding="0">
75 <tr><td valign="top"></td><td valign="top"><em>ctx</em> </td><td>the plug-in context </td></tr>
76 <tr><td valign="top"></td><td valign="top"><em>name</em> </td><td>the name of the symbol </td></tr>
77 <tr><td valign="top"></td><td valign="top"><em>ptr</em> </td><td>pointer value for the symbol </td></tr>
80 <dl class="return" compact><dt><b>Returns:</b></dt><dd><a class="el" href="group__cEnums.html#ggd6a8106d281ffa4b1f43fe8e3effc7da5ffbe0fe80af75e699e4b04909912f7a">CP_OK</a> (zero) on success or a status code on failure </dd></dl>
84 <a class="anchor" name="g8bc3b7fcf4f4ed414837f5a3998d46b7"></a><!-- doxytag: member="cpluff.h::cp_resolve_symbol" ref="g8bc3b7fcf4f4ed414837f5a3998d46b7" args="(cp_context_t *ctx, const char *id, const char *name, cp_status_t *status)" -->
86 <div class="memproto">
87 <table class="memname">
89 <td class="memname">void* cp_resolve_symbol </td>
91 <td class="paramtype"><a class="el" href="group__cTypedefsOpaque.html#gcb1aa0619dcefa746383c5e0833b62e7">cp_context_t</a> * </td>
92 <td class="paramname"> <em>ctx</em>, </td>
95 <td class="paramkey"></td>
97 <td class="paramtype">const char * </td>
98 <td class="paramname"> <em>id</em>, </td>
101 <td class="paramkey"></td>
103 <td class="paramtype">const char * </td>
104 <td class="paramname"> <em>name</em>, </td>
107 <td class="paramkey"></td>
109 <td class="paramtype"><a class="el" href="group__cEnums.html#gd6a8106d281ffa4b1f43fe8e3effc7da">cp_status_t</a> * </td>
110 <td class="paramname"> <em>status</em></td><td> </td>
115 <td></td><td></td><td width="100%"></td>
122 Resolves a symbol provided by the specified plug-in.
124 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 <a class="el" href="group__cFuncsSymbols.html#g150629125a61ac9fa4e2095b0d9c7e57">cp_release_symbol</a> when it is not needed anymore. Pointers obtained from this function must not be passed on to other plug-ins or the main program.<p>
125 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 <a class="el" href="group__cFuncsSymbols.html#g150629125a61ac9fa4e2095b0d9c7e57">cp_release_symbol</a>.<p>
126 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.<p>
127 <dl compact><dt><b>Parameters:</b></dt><dd>
128 <table border="0" cellspacing="2" cellpadding="0">
129 <tr><td valign="top"></td><td valign="top"><em>ctx</em> </td><td>the plug-in context </td></tr>
130 <tr><td valign="top"></td><td valign="top"><em>id</em> </td><td>the identifier of the symbol defining plug-in </td></tr>
131 <tr><td valign="top"></td><td valign="top"><em>name</em> </td><td>the name of the symbol </td></tr>
132 <tr><td valign="top"></td><td valign="top"><em>status</em> </td><td>a pointer to the location where the status code is to be stored, or NULL </td></tr>
135 <dl class="return" compact><dt><b>Returns:</b></dt><dd>the pointer associated with the symbol or NULL on failure </dd></dl>
139 <a class="anchor" name="g150629125a61ac9fa4e2095b0d9c7e57"></a><!-- doxytag: member="cpluff.h::cp_release_symbol" ref="g150629125a61ac9fa4e2095b0d9c7e57" args="(cp_context_t *ctx, const void *ptr)" -->
140 <div class="memitem">
141 <div class="memproto">
142 <table class="memname">
144 <td class="memname">void cp_release_symbol </td>
146 <td class="paramtype"><a class="el" href="group__cTypedefsOpaque.html#gcb1aa0619dcefa746383c5e0833b62e7">cp_context_t</a> * </td>
147 <td class="paramname"> <em>ctx</em>, </td>
150 <td class="paramkey"></td>
152 <td class="paramtype">const void * </td>
153 <td class="paramname"> <em>ptr</em></td><td> </td>
158 <td></td><td></td><td width="100%"></td>
165 Releases a previously obtained symbol.
167 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 <a class="el" href="group__cFuncsSymbols.html#g8bc3b7fcf4f4ed414837f5a3998d46b7">cp_resolve_symbol</a> for the same plug-in and symbol.<p>
168 <dl compact><dt><b>Parameters:</b></dt><dd>
169 <table border="0" cellspacing="2" cellpadding="0">
170 <tr><td valign="top"></td><td valign="top"><em>ctx</em> </td><td>the plug-in context </td></tr>
171 <tr><td valign="top"></td><td valign="top"><em>ptr</em> </td><td>the pointer associated with the symbol </td></tr>
179 <a href="http://www.c-pluff.org/">C-Pluff</a>, a plug-in framework for C<br>
180 Copyright 2007 <a href="http://www.jlehtinen.net/">Johannes Lehtinen</a>
182 <p class="generated-by">
183 Generated on Fri Apr 6 15:40:55 2007 for C-Pluff C API by <a href="http://www.doxygen.org/index.html"><img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.1