/** Initialise the OPAL system, returning a "handle" to the system that must
    be used in other calls to OPAL.

    The version parameter indicates the version of the API being used by the
    caller. It should always be set to the constant OPAL_C_API_VERSION. On
    return the library will indicate the API version it supports, if it is
    lower than that provided by the application.

    The C string options are space separated tokens indicating various options
    to be enabled, for example the protocols to be available. NULL or an empty
    string will load all available protocols. The current protocol tokens are:
        <code>
        sip sips h323 h323s iax2 pc local pots pstn ivr
        </code>
    The above protocols are in priority order, so if a protocol is not
    explicitly in the address, then the first one of the opposite "category"
    s used. There are two categories, network protocols (sip, h323, iax & pstn)
    and non-network protocols (pc, local, pots & ivr).

    Additional options are in similar form to command line arguments:
        <table border=0>
        <tr><td>-t or --trace         <td>Enable trace log. Multiple instances
                                          increase the trace level.
        <tr><td>-l or --trace-level X <td>Enable trace log and set level to X.
        <tr><td>-o or --output "name" <td>Set the filename for trace log output.
        <tr><td>-l or --trace-option X <td>Enable trace log option, use +X or -X
                                           to add/remove option where X is one of:
            <table>
            <tr><td>block    <td>PTrace::Block constructs in output
            <tr><td>time     <td>time since prgram start
            <tr><td>date     <td>date and time
            <tr><td>gmt      <td>Date/time is in UTC
            <tr><td>thread   <td>thread name and identifier
            <tr><td>level    <td>log level
            <tr><td>file     <td>source file name and line number
            <tr><td>object   <td>PObject pointer
            <tr><td>context  <td>context identifier
            <tr><td>daily    <td>rotate output file daily
            <tr><td>hour     <td>rotate output file hourly
            <tr><td>minute   <td>rotate output file every minute
            <tr><td>append   <td>append to output file, otherwise overwrites
                             &lt;perm&gt; <td>file permission similar to unix chmod,
                             but starts with +/- and only has one combination at a
                             time, e.g. +uw is user write, +or is other read, etc
            </table>
        <tr><td>-c or --config "dir"  <td>Configuration file or directory.
        <tr><td>-p or --plugin "dir"  <td>Plugin module directory.
        <tr><td>-m or --manaufacturer "str" <td>Manufacturer name for application.
        <tr><td>-n or --name "str"    <td>Product name for application.
        <tr><td>-M or --major X       <td>Major version number.
        <tr><td>-N or --minor X       <td>Minor version number.
        <tr><td>-R or --status X      <td>Code status ("alpha", "beta" or "release").
        <tr><td>-B or --build X       <td>Build/patch number.
        </table>
    It should also be noted that there must not be spaces around the '=' sign
    in the above options.

    If NULL is returned then an initialisation error occurred. This can only
    really occur if the user specifies prefixes which are not supported by
    the library.

    Example:
      <code>
      OpalHandle hOPAL;
      unsigned   version;

      version = OPAL_C_API_VERSION;
      if ((hOPAL = OpalInitialise(&version,
                                  OPAL_PREFIX_H323  " "
                                  OPAL_PREFIX_SIP   " "
                                  OPAL_PREFIX_IAX2  " "
                                  OPAL_PREFIX_PCSS
                                  " TraceLevel=4")) == NULL) {
        fputs("Could not initialise OPAL\n", stderr);
        return false;
      }
      </code>
  */
extern OpalHandle OPAL_EXPORT OpalInitialise(unsigned * version, const char * options);

/** String representation of the OpalIntialise() which may be used for late
    binding to the library.
 */
#if _WIN32
  #define OPAL_INITIALISE_FUNCTION MAKEINTRESOURCE(1)
#else
  #define OPAL_INITIALISE_FUNCTION "OpalInitialise"
#endif