docs/reference/blorb-library.sgml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
   4 ]>
   5 <refentry id="chimara-What-the-Library-Does">
   6 <refmeta>
   7 <refentrytitle>What the Library Does</refentrytitle>
   8 <manvolnum>3</manvolnum>
   9 <refmiscinfo>CHIMARA Library</refmiscinfo>
  10 </refmeta>
  11 <refnamediv>
  12 <refname>What the Library Does</refname>
  13 <refpurpose>How to implement the Blorb layer in your library</refpurpose>
  14 </refnamediv>
  15 <refsect1>
  16 <title>Description</title>
  17 <para>
  18 Each library must implement <link linkend="giblorb-set-resource-map"><function>giblorb_set_resource_map()</function></link>, if it wishes to support Blorb at all. Generally, this function should create a Blorb map and stash it away somewhere. It may also want to stash the stream itself, so that the library can read data directly from it.
  19 </para>
  20 <para>
  21 <link linkend="giblorb-set-resource-map"><function>giblorb_set_resource_map()</function></link> should return <link linkend="giblorb-err-None"><constant>giblorb_err_None</constant></link> (0) if it succeeded, or the appropriate Blorb error code if not. See <link linkend="chimara-Blorb-Errors">Blorb Errors</link>.
  22 </para>
  23 <para>
  24 The library must also link in the <filename>gi_blorb.c</filename> file. Most of this should compile without difficulty on any platform. However, it does need to allocate memory. As supplied, <filename>gi_blorb.c</filename> calls the ANSI functions <function>malloc()</function>, <function>realloc()</function>, and <function>free()</function>. If this is not appropriate on your OS, feel free to change these calls. They are isolated at the end of the file.
  25 </para>
  26 <note><title>Chimara</title>
  27 <para>
  28 The Chimara library uses the GLib functions <link linkend="g-malloc"><function>g_malloc()</function></link>, <link linkend="g-realloc"><function>g_realloc()</function></link>, and <link linkend="g-free"><function>g_free()</function></link> because of their additional error-checking features.
  29 </para></note>
  30 </refsect1>
  31 </refentry>