From ed249509edc9770362f75d1e2274ce53537687e7 Mon Sep 17 00:00:00 2001 From: Mehdi Achour Date: Sun, 10 Jun 2007 22:24:18 +0000 Subject: [PATCH] ref.ircg: switch to new doc style git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@237371 c90b9560-bf6c-de11-be94-00142212c4b1 --- .../ircg/functions/ircg-channel-mode.xml | 65 +++++++- reference/ircg/functions/ircg-disconnect.xml | 49 +++++- .../functions/ircg-eval-ecmascript-params.xml | 16 +- .../ircg/functions/ircg-fetch-error-msg.xml | 49 ++++-- .../ircg/functions/ircg-get-username.xml | 39 ++++- reference/ircg/functions/ircg-html-encode.xml | 46 +++++- reference/ircg/functions/ircg-ignore-add.xml | 60 +++++-- reference/ircg/functions/ircg-ignore-del.xml | 50 +++++- reference/ircg/functions/ircg-invite.xml | 52 ++++++- .../ircg/functions/ircg-is-conn-alive.xml | 39 ++++- reference/ircg/functions/ircg-join.xml | 52 ++++++- reference/ircg/functions/ircg-kick.xml | 61 +++++++- reference/ircg/functions/ircg-list.xml | 65 ++++++-- .../functions/ircg-lookup-format-messages.xml | 47 ++++-- reference/ircg/functions/ircg-lusers.xml | 48 +++++- reference/ircg/functions/ircg-msg.xml | 80 ++++++++-- reference/ircg/functions/ircg-names.xml | 64 ++++++-- reference/ircg/functions/ircg-nick.xml | 49 ++++-- .../ircg/functions/ircg-nickname-escape.xml | 40 ++++- .../ircg/functions/ircg-nickname-unescape.xml | 40 ++++- reference/ircg/functions/ircg-notice.xml | 49 +++++- reference/ircg/functions/ircg-oper.xml | 50 +++++- reference/ircg/functions/ircg-part.xml | 41 ++++- reference/ircg/functions/ircg-pconnect.xml | 147 ++++++++++++------ .../ircg-register-format-messages.xml | 142 ++++++++++------- reference/ircg/functions/ircg-set-current.xml | 41 ++++- reference/ircg/functions/ircg-set-file.xml | 47 +++++- reference/ircg/functions/ircg-set-on-die.xml | 72 +++++++-- reference/ircg/functions/ircg-topic.xml | 53 ++++++- reference/ircg/functions/ircg-who.xml | 69 ++++++-- reference/ircg/functions/ircg-whois.xml | 45 +++++- 31 files changed, 1449 insertions(+), 318 deletions(-) diff --git a/reference/ircg/functions/ircg-channel-mode.xml b/reference/ircg/functions/ircg-channel-mode.xml index e06f807e74..4b76025e0f 100644 --- a/reference/ircg/functions/ircg-channel-mode.xml +++ b/reference/ircg/functions/ircg-channel-mode.xml @@ -1,13 +1,13 @@ - - + ircg_channel_mode Set channel mode flags for user - - Description + + + &reftitle.description; boolircg_channel_mode resourceconnection @@ -21,13 +21,62 @@ are passed in mode_spec and are applied to the user specified by nick. + + + + &reftitle.parameters; - Mode flags are set or cleared by specifying 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', as passed as mode_spec. + + + connection + + + A connection resource handle returned by + ircg_pconnect. + + + + + channel + + + The channel name as #name. + + + + + mode_spec + + + The mode to be applied on nick. + + + Mode flags are set or cleared by specifying 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', as passed as mode_spec. + + + + + nick + + + The user on which to apply the given mode. + + + + + + + &reftitle.returnvalues; + + &return.success; + + + - + ircg_disconnect Close connection to server - - Description + + + &reftitle.description; boolircg_disconnect resourceconnection @@ -18,10 +18,49 @@ connection to a server previously established with ircg_pconnect. + + + + &reftitle.parameters; - See also: ircg_pconnect. + + + connection + + + A connection resource handle returned by + ircg_pconnect. + + + + + reason + + + A message for the disconnection. + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + + &reftitle.seealso; + + + ircg_pconnect + + + + + ircg_eval_ecmascript_params Decodes a list of JS-encoded parameters - - Description + + + &reftitle.description; arrayircg_eval_ecmascript_params stringparams @@ -24,12 +25,17 @@ * State 4: Looking for ",", skipping whitespace */ + + + &reftitle.seealso; - See also - ircg_lookup_format_messages. + + ircg_lookup_format_messages + + - + ircg_fetch_error_msg Returns the error from previous IRCG operation - - Description + + + &reftitle.description; arrayircg_fetch_error_msg resourceconnection @@ -16,13 +16,39 @@ ircg_fetch_error_msg returns the error from a failed connection. - - - Error code is stored in first array element, error text in second. - The error code is equivalent to IRC reply codes as defined by - RFC 2812. - - + + + + &reftitle.parameters; + + + + connection + + + A connection resource handle returned by + ircg_pconnect. + + + + + + + + + &reftitle.returnvalues; + + Returns an indexed array where the error code is stored in first element, + and the error text in second. + + + The error code is equivalent to IRC reply codes as defined by + RFC 2812. + + + + + &reftitle.examples; <function>ircg_fetch_error_msg</function> example @@ -40,6 +66,7 @@ if (!ircg_join ($id, "#php")) { + - + ircg_get_username Get username for connection - - Description + + + &reftitle.description; stringircg_get_username resourceconnection - Function ircg_get_username returns the - username for the specified connection connection. - Returns &false; if connection died or is - not valid. + ircg_get_username returns the username for the + specified connection connection. + + + &reftitle.parameters; + + + + connection + + + A connection resource handle returned by + ircg_pconnect. + + + + + + + + + &reftitle.returnvalues; + + Returns the username, or &false; on error. + + + - + ircg_html_encode Encodes HTML preserving output - - Description + + + &reftitle.description; stringircg_html_encode stringhtml_string @@ -22,6 +22,44 @@ HTML and escapes certain entities. + + + &reftitle.parameters; + + + + html_string + + + The HTML string to be encoded. + + + + + auto_links + + + + + + + conv_br + + + + + + + + + + + &reftitle.returnvalues; + + Returns the encoded HTML string. + + + - + ircg_ignore_add Add a user to your ignore list on a server - - Description + + + &reftitle.description; voidircg_ignore_add resourceconnection stringnick - This function adds user nick to the - ignore list of connection - connection. Afterwards, IRCG will suppress - all messages from this user through the associated connection. - - - See also: ircg_ignore_del. + This function adds user nick to the ignore list of + the connection. Afterwards, IRCG will suppress all + messages from this user through the associated connection. + + + &reftitle.parameters; + + + + connection + + + A connection resource handle returned by + ircg_pconnect. + + + + + nick + + + The user to be ignored. + + + + + + + + + &reftitle.returnvalues; + + &return.void; + + + + + &reftitle.seealso; + + + ircg_ignore_del + + + + - + ircg_ignore_del Remove a user from your ignore list on a server - - Description + + + &reftitle.description; boolircg_ignore_del resourceconnection @@ -17,10 +17,50 @@ This function removes user nick from the IRCG ignore list associated with connection. + + + + &reftitle.parameters; - See also: ircg_ignore_add. + + + connection + + + A connection resource handle returned by + ircg_pconnect. + + + + + nick + + + The user nick name. + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + + + &reftitle.seealso; + + + ircg_ignore_add + + + + + ircg_invite Invites nickname to channel - - Description + + + &reftitle.description; boolircg_invite resourceconnection @@ -15,10 +16,51 @@ ircg_invite will send an invitation to the - user nickname, prompting him to join - channel. &return.success; + user nickname, prompting him to join the given + channel. + + + &reftitle.parameters; + + + + connection + + + A connection resource handle returned by + ircg_pconnect. + + + + + channel + + + The channel name as #name. + + + + + nickname + + + The user nick name. + + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + - + ircg_is_conn_alive Check connection status - - Description + + + &reftitle.description; boolircg_is_conn_alive resourceconnection - ircg_is_conn_alive returns &true; if - connection is still alive and working or - &false;, if the connection has died for some reason. + ircg_is_conn_alive checks the + connection status. + + + &reftitle.parameters; + + + + connection + + + A connection resource handle returned by + ircg_pconnect. + + + + + + + + + &reftitle.returnvalues; + + Returns &true; if connection is still alive and + working or &false;, if the connection has died for some reason. + + + - + ircg_join Join a channel on a connected server - - Description + + + &reftitle.description; boolircg_join resourceconnection @@ -16,10 +16,50 @@ Join the channel channel on the server - connected to by connection. IRCG will - optionally pass the room key key. + connected to by connection. + + + &reftitle.parameters; + + + + connection + + + A connection resource handle returned by + ircg_pconnect. + + + + + channel + + + The channel name as #name. + + + + + key + + + An optional password for the room. + + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + - + ircg_kick Kick a user out of a channel on server - - Description + + + &reftitle.description; boolircg_kick resourceconnection @@ -18,11 +18,58 @@ Kick user nick from channel on server connected to by - connection. reason - should give a short message describing why this action was - performed. + connection. + + + &reftitle.parameters; + + + + connection + + + A connection resource handle returned by + ircg_pconnect. + + + + + channel + + The channel name as #name. + + + + + nick + + + The user to be kicked. + + + + + reason + + + reason should give a short message describing + why this action was performed. + + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + ircg_list List topic/user count of channel(s) - - Description + + + &reftitle.description; boolircg_list resourceconnection @@ -17,8 +18,43 @@ channel. The answer is sent to the output defined by ircg_set_file or ircg_set_current. - &return.success; + + + + &reftitle.parameters; + + + + connection + + + A connection resource handle returned by + ircg_pconnect. + + + + + channel + + + The channel name as #name. + + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + + &reftitle.examples; <function>ircg_list</function> example @@ -52,9 +88,7 @@ readfile('irc_output.html'); ?> ]]> - - This example will output something similar to: - + &example.outputs.similar; - - See also: ircg_set_file, - ircg_set_current, and - ircg_who. - + + + &reftitle.seealso; + + + ircg_set_file + ircg_set_current + ircg_who + + + + - + ircg_lookup_format_messages Check for the existence of a format message set - - Description + + + &reftitle.description; boolircg_lookup_format_messages stringname @@ -16,13 +16,42 @@ Check for the existence of the format message set name. Sets may be registered with ircg_register_format_messages, a default set - named ircg is always available. Returns &true;, - if the set exists and &false; otherwise. - - - See also: ircg_register_format_messages + named ircg is always available. + + + &reftitle.parameters; + + + + name + + + The format message set name. + + + + + + + + + &reftitle.returnvalues; + + Returns &true; if the set exists, &false; otherwise. + + + + + &reftitle.seealso; + + + ircg_register_format_messages + + + + + ircg_lusers IRC network statistics - - Description + + + &reftitle.description; boolircg_lusers resourceconnection @@ -17,13 +18,44 @@ connection. The answer is sent to the output defined by ircg_set_file or ircg_set_current. - &return.success; - - - See also: ircg_set_file, and - ircg_set_current. + + + &reftitle.parameters; + + + + connection + + + A connection resource handle returned by + ircg_pconnect. + + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + + &reftitle.seealso; + + + ircg_set_file + ircg_set_current + ircg_who + + + + - + ircg_msg Send message to channel or user on server - - Description + + + &reftitle.description; boolircg_msg resourceconnection @@ -17,21 +17,67 @@ ircg_msg will send the message to a channel - or user on the server connected to by - connection. A - recipient starting with - # or & will send the - message to a channel, anything else will - be interpreted as a username. - - - Setting the optional parameter suppress to - a &true; value will suppress output of your message to your own - connection. This so-called loopback is - necessary, because the IRC server does not echo PRIVMSG commands - back to us. + or user on the server. + + + &reftitle.parameters; + + + + connection + + + A connection resource handle returned by + ircg_pconnect. + + + + + recipient + + + + + A recipient starting with # + or & will send the + message to a channel, anything else will be + interpreted as a username. + + + + + message + + + The message to be sent. + + + + + suppress + + + Setting the optional parameter suppress to + a &true; value will suppress output of your message to your own + connection. This so-called loopback is + necessary, because the IRC server does not echo PRIVMSG commands + back to us. + + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + ircg_names Query visible usernames - - Description + + + &reftitle.description; boolircg_names intconnection @@ -14,16 +15,59 @@ stringtarget - &warn.undocumented.func; - - - - See also - ircg_get_username and - ircg_lusers. + + + &reftitle.parameters; + + + + connection + + + A connection resource handle returned by + ircg_pconnect. + + + + + channel + + + The channel name as #name. + + + + + target + + + + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + + &reftitle.seealso; + + + ircg_get_username + ircg_lusers + + + + - + ircg_nick Change nickname on server - - Description + + + &reftitle.description; boolircg_nick resourceconnection stringnick - Change your nickname on the given - connection to the one given in - nick, if possible. - - - Will return &true; on success and &false; on failure. + Change your nickname on the given connection to the + specified one, if possible. + + + &reftitle.parameters; + + + + connection + + + A connection resource handle returned by + ircg_pconnect. + + + + + nick + + + The new nick name for the current user. + + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + - + ircg_nickname_escape Encode special characters in nickname to be IRC-compliant - - Description + + + &reftitle.description; stringircg_nickname_escape stringnick @@ -16,10 +16,40 @@ Function ircg_nickname_escape returns an encoded nickname specified by nick which is IRC-compliant. + + + + &reftitle.parameters; - See also: ircg_nickname_unescape + + + nick + + + + + + + + + &reftitle.returnvalues; + + An IRC-compliant nick name. + + + + + + &reftitle.seealso; + + + ircg_nickname_unescape + + + + - + ircg_nickname_unescape Decodes encoded nickname - - Description + + + &reftitle.description; stringircg_nickname_unescape stringnick @@ -16,10 +16,40 @@ Function ircg_nickname_unescape returns a decoded nickname, which is specified in nick. + + + + &reftitle.parameters; - See also: ircg_nickname_escape + + + nick + + + The encoded nick name. + + + + + + + &reftitle.returnvalues; + + Returns the decoded nick name. + + + + + &reftitle.seealso; + + + ircg_nickname_escape + + + + - + ircg_notice Send a notice to a user on server - - Description + + + &reftitle.description; boolircg_notice resourceconnection @@ -22,6 +22,47 @@ in contrast to other message types. + + + &reftitle.parameters; + + + + connection + + + A connection resource handle returned by + ircg_pconnect. + + + + + nick + + + The destination user. + + + + + message + + + The message contents. + + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + ircg_oper Elevates privileges to IRC OPER - - Description + + + &reftitle.description; boolircg_oper resourceconnection @@ -16,10 +17,49 @@ ircg_oper will authenticate the logged in user on connection as an IRC operator. - name and password must - match a registered IRC operator account. &return.success; + + + &reftitle.parameters; + + + + connection + + + A connection resource handle returned by + ircg_pconnect. + + + + + name + + + The operator account name. Must be a registered IRC account. + + + + + password + + + The password associated with name. + + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + - + ircg_part Leave a channel on server - - Description + + + &reftitle.description; boolircg_part resourceconnection @@ -18,6 +18,39 @@ connected to by connection. + + + &reftitle.parameters; + + + + connection + + + A connection resource handle returned by + ircg_pconnect. + + + + + channel + + + The channel name as #name. + + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + - + ircg_pconnect Connect to an IRC server - - Description + + + &reftitle.description; resourceircg_pconnect stringusername @@ -19,49 +19,106 @@ boolbailout_on_trivial - ircg_pconnect will try to establish a - connection to an IRC server and return a connection resource - handle for further use. - - - The only mandatory parameter is username, - this will set your initial nickname on the - server. server_ip and - server_port are optional and default to - 127.0.0.1 and 6667. - - - For now parameter server_ip will not do - any hostname lookups and will only accept IP addresses in - numerical form. DNS lookups are expensive and should be done in the - context of IRCG. - - - - - You can customize the output of IRC messages and events by - selecting a format message set previously created with - ircg_register_format_messages by specifying - the set's name in msg_format. - - - If you want to handle CTCP messages such as ACTION (/me), you need to - define a mapping from CTCP type (e.g. ACTION) to a custom format - string. Do this by passing an associative array as - ctcp_messages. The keys of the array - are the CTCP type and the respective value is the format message. - - - You can define "ident", "password", and "realname" tokens which - are sent to the IRC server by setting these in an associative - array. Pass that array as user_settings. - - - See also: ircg_disconnect, - ircg_is_conn_alive, - ircg_register_format_messages. + ircg_pconnect will try to establish a connection to + an IRC server. + + + &reftitle.parameters; + + + + username + + + The initial nickname on the server. + + + + + server_ip + + + The IRC server address. + + + server_ip must be an IP address in numerical + form. DNS lookups are expensive and should be done in the context of + IRCG. Default to 127.0.0.1. + + + + + server_port + + + The server port number. Default to 6667. + + + + + msg_format + + + You can customize the output of IRC messages and events by selecting a + format message set previously created with + ircg_register_format_messages by specifying + the set's name in msg_format. + + + + + ctcp_messages + + + If you want to handle CTCP messages such as ACTION (/me), you need to + define a mapping from CTCP type (e.g. ACTION) to a custom format + string. Do this by passing an associative array as + ctcp_messages. The keys of the array + are the CTCP type and the respective value is the format message. + + + + + user_settings + + + You can define "ident", "password", and "realname" tokens which + are sent to the IRC server by setting these in this associative + array. + + + + + bailout_on_trivial + + + + + + + + + + + &reftitle.returnvalues; + + Returns a connection resource handle for further use, or &false; on error. + + + + + &reftitle.seealso; + + + ircg_disconnect + ircg_is_conn_alive + ircg_register_format_messages + + + + - + ircg_register_format_messages Register a format message set - - Description + + + &reftitle.description; boolircg_register_format_messages stringname @@ -18,59 +18,93 @@ customize the way your IRC output looks like or which script functions are invoked on the client side. + + + + &reftitle.parameters; - - Plain channel message - Private message received - Private message sent - Some user leaves channel - Some user enters channel - - Some user was kicked from the channel - - Topic has been changed - Error - Fatal error - Join list end(?) - Self part(?) - Some user changes his nick - - Some user quits his connection - - Mass join begin - Mass join element - Mass join end - Whois user - Whois server - Whois idle - Whois channel - Whois end - - Voice status change on user - - - Operator status change on user - - Banlist - Banlist end - - - %f - from - %t - to - %c - channel - %r - plain message - %m - encoded message - %j - js encoded message - - - 1 - mod encode - 2 - nickname decode - - - - See also: ircg_lookup_format_messages. + + + name + + + + + + + messages + + + + Plain channel message + Private message received + Private message sent + Some user leaves channel + Some user enters channel + + Some user was kicked from the channel + + Topic has been changed + Error + Fatal error + Join list end(?) + Self part(?) + Some user changes his nick + + Some user quits his connection + + Mass join begin + Mass join element + Mass join end + Whois user + Whois server + Whois idle + Whois channel + Whois end + + Voice status change on user + + + Operator status change on user + + Banlist + Banlist end + + + %f - from + %t - to + %c - channel + %r - plain message + %m - encoded message + %j - js encoded message + + + 1 - mod encode + 2 - nickname decode + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + + &reftitle.seealso; + + + ircg_lookup_format_messages + + + + - + ircg_set_current Set current connection for output - - Description + + + &reftitle.description; boolircg_set_current resourceconnection @@ -19,10 +19,41 @@ output while using default formatting or a format message set specified by ircg_register_format_messages. + + + + &reftitle.parameters; - See also: ircg_register_format_messages. + + + connection + + + A connection resource handle returned by + ircg_pconnect. + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + + &reftitle.seealso; + + + ircg_register_format_messages + + + + - + ircg_set_file Set logfile for connection - - Description + + + &reftitle.description; boolircg_set_file resourceconnection stringpath - Function ircg_set_file specifies a logfile - path in which all output from connection - connection will be logged. - Returns &true; on success, otherwise &false;. + ircg_set_file specifies a logfile in which all output + from the current connection will be logged. + + + &reftitle.parameters; + + + + connection + + + A connection resource handle returned by + ircg_pconnect. + + + + + path + + + Path to the logfile. + + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + - + ircg_set_on_die Set action to be executed when connection dies - - Description + + + &reftitle.description; boolircg_set_on_die resourceconnection @@ -16,18 +16,72 @@ stringdata - In case of the termination of connection connection - IRCG will connect to host at - port (Note: host must be an IPv4 address, - IRCG does not resolve host-names due to blocking issues), send + In case of the termination of the connection, IRCG + will connect to the specified host, send data to the new host connection and will wait until the remote part closes connection. This can be used to trigger a PHP script for example. + + + + &reftitle.parameters; - This feature requires IRCG 3. + + + connection + + + A connection resource handle returned by + ircg_pconnect. + + + + + host + + + This must be an IPv4 address as IRCG does not resolve host-names due + to blocking issues. + + + + + port + + + The port number. + + + + + data + + + The data to be sent before closing the connection. + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + + &reftitle.notes; + + + This feature requires IRCG 3. + + + + - + ircg_topic Set topic for channel on server - - Description + + + &reftitle.description; boolircg_topic resourceconnection @@ -15,11 +15,50 @@ stringnew_topic - Change the topic for channel channel on - the server connected to by connection to - new_topic. + Change the topic for the channel. + + + &reftitle.parameters; + + + + connection + + + A connection resource handle returned by + ircg_pconnect. + + + + + channel + + + The channel name as #name. + + + + + new_topic + + + The new topic to be set. + + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + ircg_who Queries server for WHO information - - Description + + + &reftitle.description; boolircg_who resourceconnection @@ -15,22 +16,66 @@ ircg_who will request a list of users - whose nickname is matching mask on connected - network connection. The optional parameter - ops_only will shrink the list to server - operators only. + whose nickname is matching the given mask. The answer is sent to the output defined by ircg_set_file or ircg_set_current. - &return.success; - - - See also: ircg_set_file, and - ircg_set_current. + + + &reftitle.parameters; + + + + connection + + + A connection resource handle returned by + ircg_pconnect. + + + + + mask + + + A mask for the nickname. + + + + + ops_only + + + The optional parameter ops_only will shrink the + list to server operators only. + + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + + &reftitle.seealso; + + + ircg_set_file + ircg_set_current + + + + - + ircg_whois Query server for user information - - Description + + + &reftitle.description; boolircg_whois resourceconnection stringnick - Sends a query to the connected server - connection to ask for information about the - specified user nick. + Sends a query to ask for information about the specified user. + + + &reftitle.parameters; + + + + connection + + + A connection resource handle returned by + ircg_pconnect. + + + + + nick + + + The user nick name. + + + + + + + + + &reftitle.returnvalues; + + &return.success; + + +