<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.2 $ -->
 <reference id="ref.ircg">
  <title>IRC Gateway Functions</title>
  <titleabbrev>IRC Gateway</titleabbrev>
  <partintro>
   <para>
    Internet Relay Chat Gateway ...
   </para>
   <para>
    Based on <ulink url="&url.ircg;">IRCG</ulink>, from Sascha Schumann.
   </para>
  </partintro>

  <refentry id="function.ircg-pconnect">
   <refnamediv>
    <refname>ircg_pconnect</refname>
    <refpurpose>
     Connect to an IRC server
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>resource</type><methodname>ircg_pconnect</methodname>
      <methodparam><type>string</type><parameter>username</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>server_ip</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>server_port</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>msg_format</parameter></methodparam>
      <methodparam choice="opt"><type>array</type><parameter>ctcp_messages</parameter></methodparam>
      <methodparam choice="opt"><type>array</type><parameter>user_settings</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>ircg_pconnect</function> will try to establish a
     connection to an IRC server and return a connection resource
     handle for further use.
    </para>
    <para>
     The only mandatory parameter is <parameter>username</parameter>,
     this will set your initial nickname on the
     server. <parameter>server_ip</parameter> and
     <parameter>server_port</parameter> are optional and default to
     <literal>127.0.0.1</literal> and <literal>6667</literal>.
     <note>
      <para>
       For now parameter <parameter>server_ip</parameter> will not do
       any hostname lookups and will only accept IP addresses in
       numerical form.
      </para>
     </note>
    </para>
    <para>
     You can customize the output of IRC messages and events by
     selection a format string set previously created with
     <function>ircg_register_format_messages</function> by specifing
     the sets name in <parameter>msg_format</parameter>.
    </para>
    <para>
     <parameter>ctcp_messages</parameter>
    </para>
    <para>
     <parameter>user_settings</parameter>
    </para>
    <para>
     See also: <function>ircg_disconnect</function>,
     <function>ircg_is_conn_alive</function>,
     <function>ircg_register_format_messages</function>.
    </para>
   </refsect1>
  </refentry>
  <refentry id="function.ircg-fetch-error-msg">
   <refnamediv>
    <refname>ircg_fetch_error_msg</refname>
    <refpurpose>
     Returns the error from previous ircg operation
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>array</type><methodname>ircg_fetch_error_msg</methodname>
      <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>ircg_fetch_error_msg</function> returns the error from
     the last called ircg function.
    </para>
    <note>
     <para>
      Errorcode is stored in first array element, errortext in second.
     </para>
    </note>
    <para>
     <example>
      <title><function>ircg_fetch_error_msg</function> example</title>
      <programlisting role="php">
<![CDATA[
if (!ircg_join ($id, "#php")) {
    $error = ircg_fetch_error_msg($id);
    print ("Can't join channel #php. Errorcode: 
            $error[0] Description: $error[1]");
}
]]>
      </programlisting>
     </example>
    </para> 
   </refsect1>
  </refentry>

  <refentry id="function.ircg-set-current">
   <refnamediv>
    <refname>ircg_set_current</refname>
    <refpurpose>
     Set current connection for output
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>boolean</type><methodname>ircg_set_current</methodname>
      <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
     </methodsynopsis>
    <para>
     Select the current connection for output in this execution
     context. Every output sent from the server connected to by
     <parameter>connection</parameter> will be copied to standard
     output while using default formating or a formar string set
     specified by <function>ircg_register_format_messages</function>
     and selected by <function>ircg_lookup_format_messages</function>.
    </para>
    <para>
     See also: <function>ircg_register_format_messages</function> and
     <function>ircg_lookup_format_messages</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ircg-join">
   <refnamediv>
    <refname>ircg_join</refname>
    <refpurpose>
     Join a channel on a connected server
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>boolean</type><methodname>ircg_join</methodname>
      <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
      <methodparam><type>string</type><parameter>channel</parameter></methodparam>
     </methodsynopsis>
    <para>
     Join the channel <parameter>channel</parameter> on the server
     connected to by <parameter>connection</parameter>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ircg-part">
   <refnamediv>
    <refname>ircg_part</refname>
    <refpurpose>
     Leave a channel on server
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>boolean</type><methodname>ircg_part</methodname>
      <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
      <methodparam><type>string</type><parameter>channel</parameter></methodparam>
     </methodsynopsis>
    <para>
     Leave the channel <parameter>channel</parameter> on the server
     connected to by <parameter>connection</parameter>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ircg-msg">
   <refnamediv>
    <refname>ircg_msg</refname>
    <refpurpose>
     Send message to channel or user on server
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>boolean</type><methodname>ircg_msg</methodname>
      <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
      <methodparam><type>string</type><parameter>recipient</parameter></methodparam>
      <methodparam><type>string</type><parameter>message</parameter></methodparam>
      <methodparam choice="opt"><type>boolean</type><parameter>suppress</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>ircg_msg</function> will send the message to a channel
     or user on the server connected to by
     <parameter>connection</parameter>. A
     <parameter>recipient</parameter> starting with
     <literal>#</literal> or <literal>&amp;</literal> will send the
     <parameter>message</parameter> to a channel, anything else will
     be interpreted as a username.
    </para>
    <para>
     Setting the optional parameter <parameter>suppress</parameter> to
     a &true; value will suppress output of your message to your own
     <parameter>connection</parameter>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ircg-notice">
   <refnamediv>
    <refname>ircg_notice</refname>
    <refpurpose>
     Send a notice to a user on server 
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>boolean</type><methodname>ircg_notice</methodname>
      <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
      <methodparam><type>string</type><parameter/></methodparam>
      <methodparam><type>string</type><parameter>message</parameter></methodparam>
     </methodsynopsis>
    <para>
     This function will send the <parameter>message</parameter> text
     to the user <parameter>nick</parameter> on the server connected
     to by <parameter>connection</parameter>. Query your IRC
     documentation of choice for the exact difference between a MSG
     and a NOTICE.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ircg-nick">
   <refnamediv>
    <refname>ircg_nick</refname>
    <refpurpose>
     Change nickname on server
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>boolean</type><methodname>ircg_nick</methodname>
      <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
      <methodparam><type>string</type><parameter>nick</parameter></methodparam>
     </methodsynopsis>
    <para>
     Change your nickname on the given
     <parameter>connection</parameter> to the one given in
     <parameter>nick</parameter> if possible.
    </para>
    <para>
     Will return &true; on success and &false; on failure.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ircg-topic">
   <refnamediv>
    <refname>ircg_topic</refname>
    <refpurpose>
     Set topic for channel on server
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>boolean</type><methodname>ircg_topic</methodname>
      <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
      <methodparam><type>string</type><parameter>channel</parameter></methodparam>
      <methodparam><type>string</type><parameter>new_topic</parameter></methodparam>
     </methodsynopsis>
    <para>
     Change the topic for channel <parameter>channel</parameter> on
     the server connected to by <parameter>connection</parameter> to
     <parameter>new_topic</parameter>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ircg-channel-mode">
   <refnamediv>
    <refname>ircg_channel_mode</refname>
    <refpurpose>
     Set channel mode flags for user
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>boolean</type><methodname>ircg_channel_mode</methodname>
      <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
      <methodparam><type>string</type><parameter>channel</parameter></methodparam>
      <methodparam><type>string</type><parameter>mode_spec</parameter></methodparam>
      <methodparam><type>string</type><parameter>nick</parameter></methodparam>
     </methodsynopsis>
    <para>
     Set channel mode flags for <parameter>channel</parameter> on
     server connected to by <parameter>connection</parameter>. Mode flags
     are passed in <parameter>mode_spec</parameter> and are applied to
     the user specified by <parameter>nick</parameter>.
    </para>
    <para>
     Mode flags are set or cleared by specifind a mode character and
     prepending it with a plus or minus character
     respectively. E.g. operator mode is granted by '+o' and revoked
     by '-o' passed as <parameter>mode_spec</parameter>.  
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ircg-html-encode">
   <refnamediv>
    <refname>ircg_html_encode</refname>
    <refpurpose>
     Encodes HTML preserving output
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>boolean</type><methodname>ircg_html_encode</methodname>
      <methodparam><type>string</type><parameter>html_string</parameter></methodparam>
     </methodsynopsis>
    <para>
     Encodes a HTML string <parameter>html_string</parameter> for
     output. This feature could be usable, e.g. if someone wants to
     discuss about an html problem.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ircg-whois">
   <refnamediv>
    <refname>ircg_whois</refname>
    <refpurpose>
     Query user information for nick on server
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>boolean</type><methodname>ircg_whois</methodname>
      <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
      <methodparam><type>string</type><parameter>nick</parameter></methodparam>
     </methodsynopsis>
    <para>
     Sends a query to the connected server
     <parameter>connection</parameter> to send information for the
     specified user <parameter>nick</parameter>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ircg-kick">
   <refnamediv>
    <refname>ircg_kick</refname>
    <refpurpose>
     Kick a user out of a channel on server
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>boolean</type><methodname>ircg_kick</methodname>
      <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
      <methodparam><type>string</type><parameter>channel</parameter></methodparam>
      <methodparam><type>string</type><parameter>nick</parameter></methodparam>
      <methodparam><type>string</type><parameter>reason</parameter></methodparam>
     </methodsynopsis>
    <para>
     Kick user <parameter>nick</parameter> from
     <parameter>channel</parameter> on server connected to by
     <parameter>connection</parameter>. <parameter>reason</parameter>
     should give a short message describing why this action was
     performed.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ircg-ignore-add">
   <refnamediv>
    <refname>ircg_ignore_add</refname>
    <refpurpose>
     Add a user to your ignore list on a server
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>boolean</type><methodname>ircg_ignore_add</methodname>
      <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
      <methodparam><type>string</type><parameter>nick</parameter></methodparam>
     </methodsynopsis>
    <para>
     This function will add user <parameter>nick</parameter> to your
     ignore list on the server connected to by
     <parameter>connection</parameter>. By doing so you will suppress
     all messages from this user from being send to you.
    </para>
    <para>
     See also: <function>ircg_ignore_del</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ircg-ignore-del">
   <refnamediv>
    <refname>ircg_ignore_del</refname>
    <refpurpose>
     Remove a user from your ignore list on a server
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>boolean</type><methodname>ircg_ignore_del</methodname>
      <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
      <methodparam><type>string</type><parameter>nick</parameter></methodparam>
     </methodsynopsis>
    <para>
     This function remove user <parameter>nick</parameter> from your
     ignore list on the server connected to by
     <parameter>connection</parameter>.
    </para>
    <para>
     See also: <function>ircg_ignore_add</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ircg-disconnect">
   <refnamediv>
    <refname>ircg_disconnect</refname>
    <refpurpose>
     Close connection to server
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>boolean</type><methodname>ircg_disconnect</methodname>
      <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
      <methodparam><type>string</type><parameter>reason</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>ircg_disconnect</function> will close a
     <parameter>connection</parameter> to a server previously
     established with <function>ircg-pconnect</function>.
    </para>
    <para>
     See also: <function>ircg_pconnect</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ircg-is-conn-alive">
   <refnamediv>
    <refname>ircg_is_conn_alive</refname>
    <refpurpose>
     Check connection status
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>boolean</type><methodname>ircg_is_conn_alive</methodname>
      <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>ircg_is_conn_alive</function> returns &true; if
     <parameter>connection</parameter> is still alive and working or
     &false; if the server no longer talks to us.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ircg-lookup-format-messages">
   <refnamediv>
    <refname>ircg_lookup_format_messages</refname>
    <refpurpose>
     Select a set of format strings for display of IRC messages
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>boolean</type><methodname>ircg_lookup_format_messages</methodname>
      <methodparam><type>string</type><parameter>name</parameter></methodparam>
     </methodsynopsis>
    <para>
     Select the set of format strings to use for display of IRC
     messages and events. Sets may be registered with
     <function>ircg_register_format_messages</function>, a default set
     named <literal>ircg</literal> is always available.
    </para>
    <para>
     See also: <function>ircg_register_format_messages</function>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ircg-register-format-messages">
   <refnamediv>
    <refname>ircg_register_format_messages</refname>
    <refpurpose>
     Register a set of format strings for display of IRC messages
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>boolean</type><methodname>ircg_register_format_messages</methodname>
      <methodparam><type>string</type><parameter>name</parameter></methodparam>
      <methodparam><type>array</type><parameter>messages</parameter></methodparam>
     </methodsynopsis>
    <para>
     With <function>ircg_register_format_messages</function> you can
     customize the way your IRC output looks like. You can even
     register different format string sets and switch between them on
     the fly with <function>ircg_lookup_format_messages</function>.
    </para>
    <para>
     <itemizedlist>
      <listitem><simpara>Plain channel message</simpara></listitem>
      <listitem><simpara>Private message received</simpara></listitem>
      <listitem><simpara>Private message sent</simpara></listitem>
      <listitem><simpara>Some user leaves channel</simpara></listitem>
      <listitem><simpara>Some user enters channel</simpara></listitem>
      <listitem>
       <simpara>Some user was kicked from the channel</simpara>
      </listitem>
      <listitem><simpara>Topic has been changed</simpara></listitem>
      <listitem><simpara>Error</simpara></listitem>
      <listitem><simpara>Fatal error</simpara></listitem>
      <listitem><simpara>Join list end(?)</simpara></listitem>
      <listitem><simpara>Self part(?)</simpara></listitem>
      <listitem><simpara>Some user changes his nick</simpara></listitem>
      <listitem>
       <simpara>Some user quits his connection</simpara>
      </listitem>
      <listitem><simpara>Mass join begin</simpara></listitem>
      <listitem><simpara>Mass join element</simpara></listitem>
      <listitem><simpara>Mass join end</simpara></listitem>
      <listitem><simpara>Whois user</simpara></listitem>
      <listitem><simpara>Whois server</simpara></listitem>
      <listitem><simpara>Whois idle</simpara></listitem>
      <listitem><simpara>Whois channel</simpara></listitem>
      <listitem><simpara>Whois end</simpara></listitem>
      <listitem>
       <simpara>Voice status change on user</simpara>
      </listitem>
      <listitem>
       <simpara>Operator status change on user</simpara>
      </listitem>
      <listitem><simpara>Banlist</simpara></listitem>
      <listitem><simpara>Banlist end</simpara></listitem>
     </itemizedlist>
     <itemizedlist>
      <listitem><simpara>%f - from</simpara></listitem>
      <listitem><simpara>%t - to</simpara></listitem>
      <listitem><simpara>%c - channel</simpara></listitem>
      <listitem><simpara>%r - plain message</simpara></listitem>
      <listitem><simpara>%m - encoded message</simpara></listitem>
      <listitem><simpara>%j - js encoded message</simpara></listitem>
     </itemizedlist>
     <itemizedlist>
      <listitem><simpara>1 - mod encode</simpara></listitem>
      <listitem><simpara>2 - nickname decode</simpara></listitem>
     </itemizedlist>
    </para>
    <para>
     See also: <function>ircg_lookup_format_messages</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id='function.ircg-set-on-die'>
   <refnamediv>
    <refname>ircg_set_on_die</refname>
    <refpurpose>
     Set hostaction to be execute when connection dies */
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>ircg_set_on_die</methodname>
      <methodparam><type>int</type><parameter>connection</parameter></methodparam>
      <methodparam><type>string</type><parameter>host</parameter></methodparam>
      <methodparam><type>int</type><parameter>port</parameter></methodparam>
      <methodparam><type>string</type><parameter>data</parameter></methodparam>
     </methodsynopsis>
    <para>
     &warn.undocumented.func;
    </para>
   </refsect1>
  </refentry>

  <refentry id='function.ircg-set-file'>
   <refnamediv>
    <refname>ircg_set_file</refname>
    <refpurpose>
     Set logfile for connection
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>ircg_set_file</methodname>
      <methodparam><type>int</type><parameter>connection</parameter></methodparam>
      <methodparam><type>string</type><parameter>path</parameter></methodparam>
     </methodsynopsis>
    <para>
     &warn.undocumented.func;
    </para>
   </refsect1>
  </refentry>

  <refentry id='function.ircg-get-username'>
   <refnamediv>
    <refname>ircg_get_username</refname>
    <refpurpose>
     Get username for connection
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>ircg_get_username</methodname>
      <methodparam><type>int</type><parameter>connection</parameter></methodparam>
     </methodsynopsis>
    <para>
     &warn.undocumented.func;
    </para>
   </refsect1>
  </refentry>

  <refentry id='function.ircg-nickname-escape'>
   <refnamediv>
    <refname>ircg_nickname_escape</refname>
    <refpurpose>
     Encode special characters in nickname to be IRC-compliant 
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>ircg_nickname_escape</methodname>
      <methodparam><type>string</type><parameter>nick</parameter></methodparam>
     </methodsynopsis>
    <para>
     &warn.undocumented.func;
    </para>
   </refsect1>
  </refentry>

  <refentry id='function.ircg-nickname-unescape'>
   <refnamediv>
    <refname>ircg_nickname_escape</refname>
    <refpurpose>
     Decode encoded nickname 
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>ircg_nickname_escape</methodname>
      <methodparam><type>string</type><parameter>nick</parameter></methodparam>
     </methodsynopsis>
    <para>
     &warn.undocumented.func;
    </para>
   </refsect1>
  </refentry>

 </reference>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->