service/protocol-plugin/lib/cpluff/doc/reference/c-api/structcp__plugin__runtime__t.html

   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: cp_plugin_runtime_t Struct Reference</title>
   4 <link href="doxygen.css" rel="stylesheet" type="text/css">
   5 <link href="tabs.css" rel="stylesheet" type="text/css">
   6 </head><body>
   7 <!-- Generated by Doxygen 1.5.1 -->
   8 <div class="tabs">
   9   <ul>
  10     <li><a href="index.html"><span>Main&nbsp;Page</span></a></li>
  11     <li><a href="modules.html"><span>Modules</span></a></li>
  12     <li id="current"><a href="annotated.html"><span>Data&nbsp;Structures</span></a></li>
  13     <li><a href="files.html"><span>Files</span></a></li>
  14     <li><a href="pages.html"><span>Related&nbsp;Pages</span></a></li>
  15   </ul></div>
  16 <div class="tabs">
  17   <ul>
  18     <li><a href="annotated.html"><span>Data&nbsp;Structures</span></a></li>
  19     <li><a href="functions.html"><span>Data&nbsp;Fields</span></a></li>
  20   </ul></div>
  21 <h1>cp_plugin_runtime_t Struct Reference<br>
  22 <small>
  23 [<a class="el" href="group__cStructs.html">Data structures</a>]</small>
  24 </h1><!-- doxytag: class="cp_plugin_runtime_t" --><hr><a name="_details"></a><h2>Detailed Description</h2>
  25 Container for plug-in runtime information.
  26 <p>
  27 A plug-in runtime defines a static instance of this structure to pass information to the plug-in framework. The plug-in framework then uses the information to create and control plug-in instances. The symbol pointing to the runtime information instance is named by the <em>funcs</em> attribute of the <em>runtime</em> element in a plug-in descriptor.<p>
  28 The following graph displays how these functions are used to control the state of the plug-in instance.<p>
  29 <div align="center">
  30 <img src="inline_dotgraph_1.png" alt="inline_dotgraph_1" border="0" usemap="#inline_dotgraph_1.map">
  31 <map name="inline_dotgraph_1.map"><area href="structcp__plugin__runtime__t.html#f193bb8481e4b6aeab275fa5908a9af9" shape="rect" coords="135,29,172,44" alt="">
  32 <area href="structcp__plugin__runtime__t.html#f193bb8481e4b6aeab275fa5908a9af9" shape="rect" coords="103,39,111,47" alt="">
  33 <area href="structcp__plugin__runtime__t.html#f193bb8481e4b6aeab275fa5908a9af9" shape="rect" coords="196,39,204,47" alt="">
  34 <area href="structcp__plugin__runtime__t.html#cc37619ea5a3ff4e39e53b9ce0e7ed4f" shape="rect" coords="131,49,176,64" alt="">
  35 <area href="structcp__plugin__runtime__t.html#cc37619ea5a3ff4e39e53b9ce0e7ed4f" shape="rect" coords="201,52,209,60" alt="">
  36 <area href="structcp__plugin__runtime__t.html#cc37619ea5a3ff4e39e53b9ce0e7ed4f" shape="rect" coords="95,52,103,60" alt="">
  37 <area href="structcp__plugin__runtime__t.html#5a6c64e5d2467d67cf4dd2498639b490" shape="rect" coords="301,29,328,44" alt="">
  38 <area href="structcp__plugin__runtime__t.html#5a6c64e5d2467d67cf4dd2498639b490" shape="rect" coords="273,39,281,47" alt="">
  39 <area href="structcp__plugin__runtime__t.html#5a6c64e5d2467d67cf4dd2498639b490" shape="rect" coords="348,39,356,47" alt="">
  40 <area href="structcp__plugin__runtime__t.html#ede7dc51a6d9f47d0e21445dc952d5d4" shape="rect" coords="301,49,328,64" alt="">
  41 <area href="structcp__plugin__runtime__t.html#ede7dc51a6d9f47d0e21445dc952d5d4" shape="rect" coords="353,52,361,60" alt="">
  42 <area href="structcp__plugin__runtime__t.html#ede7dc51a6d9f47d0e21445dc952d5d4" shape="rect" coords="268,52,276,60" alt="">
  43 </map>
  44 </div>
  45
  46 <p>
  47 <table border="0" cellpadding="0" cellspacing="0">
  48 <tr><td></td></tr>
  49 <tr><td colspan="2"><br><h2>Data Fields</h2></td></tr>
  50 <tr><td class="memItemLeft" nowrap align="right" valign="top">void *(*&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="structcp__plugin__runtime__t.html#f193bb8481e4b6aeab275fa5908a9af9">create</a> )(<a class="el" href="group__cTypedefsOpaque.html#gcb1aa0619dcefa746383c5e0833b62e7">cp_context_t</a> *ctx)</td></tr>
  51
  52 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">An initialization function called to create a new plug-in runtime instance.  <a href="#f193bb8481e4b6aeab275fa5908a9af9"></a><br></td></tr>
  53 <tr><td class="memItemLeft" nowrap align="right" valign="top">int(*&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="structcp__plugin__runtime__t.html#5a6c64e5d2467d67cf4dd2498639b490">start</a> )(void *data)</td></tr>
  54
  55 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">A start function called to start a plug-in instance.  <a href="#5a6c64e5d2467d67cf4dd2498639b490"></a><br></td></tr>
  56 <tr><td class="memItemLeft" nowrap align="right" valign="top">void(*&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="structcp__plugin__runtime__t.html#ede7dc51a6d9f47d0e21445dc952d5d4">stop</a> )(void *data)</td></tr>
  57
  58 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">A stop function called to stop a plugin instance.  <a href="#ede7dc51a6d9f47d0e21445dc952d5d4"></a><br></td></tr>
  59 <tr><td class="memItemLeft" nowrap align="right" valign="top">void(*&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="structcp__plugin__runtime__t.html#cc37619ea5a3ff4e39e53b9ce0e7ed4f">destroy</a> )(void *data)</td></tr>
  60
  61 <tr><td class="mdescLeft">&nbsp;</td><td class="mdescRight">A destroy function called to destroy a plug-in instance.  <a href="#cc37619ea5a3ff4e39e53b9ce0e7ed4f"></a><br></td></tr>
  62 </table>
  63 <hr><h2>Field Documentation</h2>
  64 <a class="anchor" name="f193bb8481e4b6aeab275fa5908a9af9"></a><!-- doxytag: member="cp_plugin_runtime_t::create" ref="f193bb8481e4b6aeab275fa5908a9af9" args=")(cp_context_t *ctx)" -->
  65 <div class="memitem">
  66 <div class="memproto">
  67       <table class="memname">
  68         <tr>
  69           <td class="memname">void*(* <a class="el" href="structcp__plugin__runtime__t.html#f193bb8481e4b6aeab275fa5908a9af9">create</a>)(<a class="el" href="group__cTypedefsOpaque.html#gcb1aa0619dcefa746383c5e0833b62e7">cp_context_t</a> *ctx)          </td>
  70         </tr>
  71       </table>
  72 </div>
  73 <div class="memdoc">
  74
  75 <p>
  76 An initialization function called to create a new plug-in runtime instance.
  77 <p>
  78 The initialization function initializes and returns an opaque plug-in instance data pointer which is then passed on to other control functions. This data pointer should be used to access plug-in instance specific data. For example, the context reference must be stored as part of plug-in instance data if the plug-in runtime needs it. On failure, the function must return NULL.<p>
  79 C-pluff API functions must not be called from within a create function invocation and symbols from imported plug-ins must not be used because they may not available yet.<p>
  80 <dl compact><dt><b>Parameters:</b></dt><dd>
  81   <table border="0" cellspacing="2" cellpadding="0">
  82     <tr><td valign="top"></td><td valign="top"><em>ctx</em>&nbsp;</td><td>the plug-in context of the new plug-in instance </td></tr>
  83   </table>
  84 </dl>
  85 <dl class="return" compact><dt><b>Returns:</b></dt><dd>an opaque pointer to plug-in instance data or NULL on failure </dd></dl>
  86
  87 </div>
  88 </div><p>
  89 <a class="anchor" name="5a6c64e5d2467d67cf4dd2498639b490"></a><!-- doxytag: member="cp_plugin_runtime_t::start" ref="5a6c64e5d2467d67cf4dd2498639b490" args=")(void *data)" -->
  90 <div class="memitem">
  91 <div class="memproto">
  92       <table class="memname">
  93         <tr>
  94           <td class="memname">int(* <a class="el" href="structcp__plugin__runtime__t.html#5a6c64e5d2467d67cf4dd2498639b490">start</a>)(void *data)          </td>
  95         </tr>
  96       </table>
  97 </div>
  98 <div class="memdoc">
  99
 100 <p>
 101 A start function called to start a plug-in instance.
 102 <p>
 103 The start function must return zero (CP_OK) on success and non-zero on failure. If the start fails then the stop function (if any) is called to clean up plug-in state. <a class="el" href="group__cFuncsInit.html">Library initialization</a>, <a class="el" href="group__cFuncsContext.html">plug-in context management</a> and <a class="el" href="group__cFuncsPlugin.html">plug-in management</a> functions must not be called from within a start function invocation. The start function pointer can be NULL if the plug-in runtime does not have a start function.<p>
 104 The start function implementation should set up plug-in and return promptly. If there is further work to be done then a plug-in can start a thread or register a run function using <a class="el" href="group__cFuncsPluginExec.html#g357c45e87ff896e8541fe3758b19a035">cp_run_function</a>. Symbols from imported plug-ins are guaranteed to be available for the start function.<p>
 105 <dl compact><dt><b>Parameters:</b></dt><dd>
 106   <table border="0" cellspacing="2" cellpadding="0">
 107     <tr><td valign="top"></td><td valign="top"><em>data</em>&nbsp;</td><td>an opaque pointer to plug-in instance data </td></tr>
 108   </table>
 109 </dl>
 110 <dl class="return" compact><dt><b>Returns:</b></dt><dd>non-zero on success, or zero on failure </dd></dl>
 111
 112 </div>
 113 </div><p>
 114 <a class="anchor" name="ede7dc51a6d9f47d0e21445dc952d5d4"></a><!-- doxytag: member="cp_plugin_runtime_t::stop" ref="ede7dc51a6d9f47d0e21445dc952d5d4" args=")(void *data)" -->
 115 <div class="memitem">
 116 <div class="memproto">
 117       <table class="memname">
 118         <tr>
 119           <td class="memname">void(* <a class="el" href="structcp__plugin__runtime__t.html#ede7dc51a6d9f47d0e21445dc952d5d4">stop</a>)(void *data)          </td>
 120         </tr>
 121       </table>
 122 </div>
 123 <div class="memdoc">
 124
 125 <p>
 126 A stop function called to stop a plugin instance.
 127 <p>
 128 This function must cease all plug-in runtime activities. <a class="el" href="group__cFuncsInit.html">Library initialization</a>, <a class="el" href="group__cFuncsContext.html">plug-in context management</a>, <a class="el" href="group__cFuncsPlugin.html">plug-in management</a> functions, <a class="el" href="group__cFuncsPluginExec.html#g357c45e87ff896e8541fe3758b19a035">cp_run_function</a> and <a class="el" href="group__cFuncsSymbols.html#g8bc3b7fcf4f4ed414837f5a3998d46b7">cp_resolve_symbol</a> must not be called from within a stop function invocation. The stop function pointer can be NULL if the plug-in runtime does not have a stop function. It is guaranteed that no run functions registered by the plug-in are called simultaneously or after the call to the stop function.<p>
 129 The stop function should release any external resources hold by the plug-in. Dynamically resolved symbols are automatically released and dynamically defined symbols and registered run functions are automatically unregistered after the call to stop function. Resolved external symbols are still available for the stop function and symbols provided by the plug-in should remain available after the call to stop function (although functionality might be limited). Final cleanup can be safely done in the destroy function.<p>
 130 <dl compact><dt><b>Parameters:</b></dt><dd>
 131   <table border="0" cellspacing="2" cellpadding="0">
 132     <tr><td valign="top"></td><td valign="top"><em>data</em>&nbsp;</td><td>an opaque pointer to plug-in instance data </td></tr>
 133   </table>
 134 </dl>
 135
 136 </div>
 137 </div><p>
 138 <a class="anchor" name="cc37619ea5a3ff4e39e53b9ce0e7ed4f"></a><!-- doxytag: member="cp_plugin_runtime_t::destroy" ref="cc37619ea5a3ff4e39e53b9ce0e7ed4f" args=")(void *data)" -->
 139 <div class="memitem">
 140 <div class="memproto">
 141       <table class="memname">
 142         <tr>
 143           <td class="memname">void(* <a class="el" href="structcp__plugin__runtime__t.html#cc37619ea5a3ff4e39e53b9ce0e7ed4f">destroy</a>)(void *data)          </td>
 144         </tr>
 145       </table>
 146 </div>
 147 <div class="memdoc">
 148
 149 <p>
 150 A destroy function called to destroy a plug-in instance.
 151 <p>
 152 This function should release any plug-in instance data. The plug-in is stopped before this function is called. C-Pluff API functions must not be called from within a destroy function invocation and symbols from imported plug-ins must not be used because they may not be available anymore. Correspondingly, it is guaranteed that the symbols provided by the plug-in are not used by other plug-ins when destroy function has been called.<p>
 153 <dl compact><dt><b>Parameters:</b></dt><dd>
 154   <table border="0" cellspacing="2" cellpadding="0">
 155     <tr><td valign="top"></td><td valign="top"><em>data</em>&nbsp;</td><td>an opaque pointer to plug-in instance data </td></tr>
 156   </table>
 157 </dl>
 158
 159 </div>
 160 </div><p>
 161 <hr>The documentation for this struct was generated from the following file:<ul>
 162 <li><a class="el" href="cpluff_8h-source.html">cpluff.h</a></ul>
 163 <hr size="1">
 164 <p class="footer">
 165 <a href="http://www.c-pluff.org/">C-Pluff</a>, a plug-in framework for C<br>
 166 Copyright 2007 <a href="http://www.jlehtinen.net/">Johannes Lehtinen</a>
 167 </p>
 168 <p class="generated-by">
 169 Generated on Fri Apr 6 15:40:57 2007 for C-Pluff C API by&nbsp;<a href="http://www.doxygen.org/index.html"><img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.1
 170 </p>
 171 </body>
 172 </html>