Functions

Output messages (in XML format) from up to five minutes ago (give somebody who's just joined the chatroom some chat backlog), or the messages posted since the last check.

_chat_messages_script_ajax(\AUTO_LINK $room_id, boolean $backlog, \?AUTO_LINK $message_id, \?AUTO_LINK $event_id, string $events_output) 

Parameters

$room_id

\AUTO_LINK

Room ID (or -1 to mean 'all' as used for IM global process, -2 to mean none)

$backlog

boolean

Output the backlog?

$message_id

\?AUTO_LINK

Latest received message ID (NULL: we're not getting latest messages)

$event_id

\?AUTO_LINK

Latest event ID (NULL: we're not getting events, but we do request a null event so we can use that as a future reference point)

$events_output

string

Events output to append

Handle an AJAX message posting request.

_chat_post_message_ajax(\AUTO_LINK $room_id, string $message, string $font, string $colour, \BINARY $first_message) 

Parameters

$room_id

\AUTO_LINK

Room ID

$message

string

The message

$font

string

Font name

$colour

string

Font colour

$first_message

\BINARY

Whether this is the first message sent out to this room, since some change

Parse invitation chat code tag.

_deal_with_chatcode_invite(string $pm_user, string $pm_message, \SHORT_TEXT $username, string $text, \ID_TEXT $zone) : array

Parameters

$pm_user

string

Comma-separated list of members to invite

$pm_message

string

The room name

$username

\SHORT_TEXT

The username of who made this chatcode

$text

string

The text we are using

$zone

\ID_TEXT

The zone the chat module is in

Returns

arrayA pair: whether the message was deleted, and the new text of the message

Parse room creation chat code tag.

_deal_with_chatcode_newroom(string $pm_user, string $pm_message, \SHORT_TEXT $username, string $text, \?integer $cutoff) : array

Parameters

$pm_user

string

The room name

$pm_message

string

Comma-separated list of members to allow in

$username

\SHORT_TEXT

The username of who made this chatcode

$text

string

The text we are using

$cutoff

\?integer

The maximum number of messages to be returned (NULL: no maximum)

Returns

arrayA pair: whether the message was deleted, and the new text of the message

Parse private message chat code tag.

_deal_with_chatcode_private(string $pm_user, string $pm_message, \SHORT_TEXT $username, string $text, \AUTO_LINK $room_id, \BINARY $system_message) : array

Parameters

$pm_user

string

The member a private message should be sent to

$pm_message

string

The private message

$username

\SHORT_TEXT

The username of who made this chatcode

$text

string

The text we are using

$room_id

\AUTO_LINK

The room ID the message is in

$system_message

\BINARY

Whether this is within a system message

Returns

arrayA pair: whether the message was deleted, and the new text of the message

Parse chat code tags (called multiple times, for each tag).

_deal_with_chatcode_tags(string $text, string $tag, string $pm_user, string $pm_message, \SHORT_TEXT $username, \?integer $cutoff, \ID_TEXT $zone, \AUTO_LINK $room_id, \BINARY $system_message) : array

Parameters

$text

string

The text we are using

$tag

string

The tag name we are parsing

$pm_user

string

1st param

$pm_message

string

2nd param

$username

\SHORT_TEXT

The username of who made this chatcode

$cutoff

\?integer

The maximum number of messages to be returned (NULL: no maximum)

$zone

\ID_TEXT

The zone that our chat module is in

$room_id

\AUTO_LINK

The room ID the message is in

$system_message

\BINARY

Whether this is within a system message

Returns

arrayA pair: whether the message was deleted, and the new text of the message

Remove any messages from the list of messages that aren't mentioned in the list of message IDs.

_remove_empty_messages(array $messages, array $message_ids) : array

Parameters

$messages

array

Original list of messages

$message_ids

array

List of message IDs to keep

Returns

arrayA new list of messages

Add a chatroom.

add_chatroom(\SHORT_TEXT $welcome, \SHORT_TEXT $roomname, \MEMBER $room_owner, \LONG_TEXT $allow2, \LONG_TEXT $allow2_groups, \LONG_TEXT $disallow2, \LONG_TEXT $disallow2_groups, \LANGUAGE_NAME $roomlang, \BINARY $is_im) : \AUTO_LINK

Parameters

$welcome

\SHORT_TEXT

The welcome message

$roomname

\SHORT_TEXT

The room name

$room_owner

\MEMBER

The room owner

$allow2

\LONG_TEXT

The comma-separated list of users that may access it (blank: no restriction)

$allow2_groups

\LONG_TEXT

The comma-separated list of usergroups that may access it (blank: no restriction)

$disallow2

\LONG_TEXT

The comma-separated list of users that may NOT access it (blank: no restriction)

$disallow2_groups

\LONG_TEXT

The comma-separated list of usergroups that may NOT access it (blank: no restriction)

$roomlang

\LANGUAGE_NAME

The room language

$is_im

\BINARY

Whether it is an IM room

Returns

\AUTO_LINKThe chat room ID

Block a member.

blocking_add(\MEMBER $blocker, \MEMBER $blocked, \?TIME $time) 

Parameters

$blocker

\MEMBER

The member blocking

$blocked

\MEMBER

The member being blocked

$time

\?TIME

The logged time of the block (NULL: now)

Unblock a member.

blocking_remove(\MEMBER $blocker, \MEMBER $blocked) 

Parameters

$blocker

\MEMBER

The member unblocking

$blocked

\MEMBER

The member being unblocked

Takes a chat message, and converts some characters from HTML entities into proper characters.

chat_convert_html_entities(string $string) : string

Parameters

$string

string

Chat message to be parsed

Returns

stringParsed chat message

Get an array of all the chatrooms.

chat_get_all_rooms() : array

Returns

arrayAn array of all the chatrooms

Get a multidimensional array of the content of the specified chatroom.

chat_get_room_content(\AUTO_LINK $room_id, array $_rooms, \?integer $cutoff, boolean $dereference, boolean $downloading, \?integer $start, \?integer $finish, \?integer $uptoid, \?ID_TEXT $zone, \?AUTO_LINK $entering_room, boolean $return_my_messages, boolean $return_system_messages) : array

It automatically parses for comcode, chatcode, banned words, smilies, and uses complex logic to decide whether or not to show each message; based upon who the member is, the message content, and other such inputs. If you set the $dereference flag, all the messages will be dereferenced for you, and if you set the $downloading flag, the array is returned in a format appropriate for things like downloading the chat logs. $start and $finish are used to cutoff the number of messages returned, based on their posting date and time, and the $uptoid variable is used to make the function only return the messages newer than the id specified.

Parameters

$room_id

\AUTO_LINK

The room ID (-1 for IM)

$_rooms

array

Rooms database rows that we'll need

$cutoff

\?integer

The maximum number of messages to be returned (NULL: no maximum)

$dereference

boolean

Whether to dereference the returned messages

$downloading

boolean

Whether to return the messages in a downloadeable format (using the templates for log downloading)

$start

\?integer

The datetime stamp to start gathering messages from (NULL: all)

$finish

\?integer

The datetime stamp to stop gathering messages at (NULL: current time)

$uptoid

\?integer

The lowest message ID to return (NULL: no special lowest number)

$zone

\?ID_TEXT

The zone the chat module is in (NULL: find it)

$entering_room

\?AUTO_LINK

The language ID for the "entering room" message (NULL: not entering the room)

$return_my_messages

boolean

Return the current user's messages?

$return_system_messages

boolean

Return system messages

Returns

arrayAn array of all the messages collected according to the search criteria

Pass out chat log files.

chat_logs_script() 

Function to quickly (efficiently) check to see if there's been any chat activity.

chat_poller() 

Enter a message into the database for the specified room, and with the specified parameters.

chat_post_message(\AUTO_LINK $room_id, \LONG_TEXT $message, \SHORT_TEXT $font_name, \SHORT_TEXT $text_colour, \SHORT_INTEGER $wrap_pos) : boolean

The message is filtered for banned words, and is compressed into a tempcode storage format.

Parameters

$room_id

\AUTO_LINK

The room ID for the message to be posted in

$message

\LONG_TEXT

The message body

$font_name

\SHORT_TEXT

The font name for the message

$text_colour

\SHORT_TEXT

The text colour for the message

$wrap_pos

\SHORT_INTEGER

The wrap position for the message

Returns

booleanWhether the message was successfully posted or not

Prune membership of chat room.

chat_room_prune(\AUTO_LINK $room_id, \?array $room_row) 

Parameters

$room_id

\AUTO_LINK

Room ID (or -1 if all rooms)

$room_row

\?array

The room row (NULL: read in from DB)

Ban a member from a chatroom.

chatroom_ban_to(\MEMBER $member_id, \AUTO_LINK $id) 

Parameters

$member_id

\MEMBER

The member to ban

$id

\AUTO_LINK

The chat room ID

Unban a member from a chatroom.

chatroom_unban_to(\MEMBER $member_id, \AUTO_LINK $id) 

Parameters

$member_id

\MEMBER

The member to unban

$id

\AUTO_LINK

The chat room ID

Find whether a member is active in chat (i.e.

chatter_active(\MEMBER $member_id, \?AUTO_LINK $room_id) : boolean

not away).

Parameters

$member_id

\MEMBER

Member ID

$room_id

\?AUTO_LINK

Room ID (NULL: lobby)

Returns

booleanWhether the member is active

Check whether a member has access to the chatroom.

check_chatroom_access(mixed $room, boolean $ret, \?MEMBER $member_id, boolean $must_be_explicit) : boolean

Parameters

$room

mixed

The row of the chat room to check for access OR it's ID (AUTO_LINK)

$ret

boolean

Whether to return false if there is no access (as opposed to bombing out)

$member_id

\?MEMBER

The member to check as (NULL: current member)

$must_be_explicit

boolean

Whether to also ensure for $member_id having explicit access

Returns

booleanWhether the current member has access to the chatroom

Delete all chatrooms.

delete_all_chatrooms() 

Delete chat messages.

delete_chat_messages(array $where) 

Parameters

$where

array

Where query to specify what to delete

Delete a chatroom.

delete_chatroom(\AUTO_LINK $id) 

Parameters

$id

\AUTO_LINK

The chat room ID

Delete all messages in a chatroom.

delete_chatroom_messages(\AUTO_LINK $id) 

Parameters

$id

\AUTO_LINK

The chat room ID

Edit a chatroom.

edit_chatroom(\AUTO_LINK $id, \SHORT_TEXT $welcome, \SHORT_TEXT $roomname, \MEMBER $room_owner, \LONG_TEXT $allow2, \LONG_TEXT $allow2_groups, \LONG_TEXT $disallow2, \LONG_TEXT $disallow2_groups, \LANGUAGE_NAME $roomlang) 

Parameters

$id

\AUTO_LINK

The chat room ID

$welcome

\SHORT_TEXT

The welcome message

$roomname

\SHORT_TEXT

The room name

$room_owner

\MEMBER

The room owner

$allow2

\LONG_TEXT

The comma-separated list of users that may access it (blank: no restriction)

$allow2_groups

\LONG_TEXT

The comma-separated list of usergroups that may access it (blank: no restriction)

$disallow2

\LONG_TEXT

The comma-separated list of users that may NOT access it (blank: no restriction)

$disallow2_groups

\LONG_TEXT

The comma-separated list of usergroups that may NOT access it (blank: no restriction)

$roomlang

\LANGUAGE_NAME

The room language

Enter the current member to the chat lobby / Mark them available.

enter_chat_lobby() 

Filter an invite list to make sure people who are blocking don't get drawn in and hence their blocking unmasked.

filter_invites_for_blocking(string $people) : string

Parameters

$people

string

Comma-separated people list

Returns

stringFiltered comma-separated people list

Add a friend.

friend_add(\MEMBER $likes, \MEMBER $liked, \?TIME $time) 

Parameters

$likes

\MEMBER

The member befriending

$liked

\MEMBER

The member being befriended

$time

\?TIME

The logged time of the friendship (NULL: now)

Remove ('dump') a friend.

friend_remove(\MEMBER $likes, \MEMBER $liked) 

Parameters

$likes

\MEMBER

The member befriending

$liked

\MEMBER

The member being dumped

Get a template that will set up the chat sound effects as for what this member needs.

get_chat_sound_tpl() : \tempcode

Returns

\tempcodeTemplate to set up chat sound effects.

Get form fields for adding/editing a chatroom.

get_chatroom_fields(boolean $is_made_by_me, \SHORT_TEXT $room_name, \LONG_TEXT $welcome, \SHORT_TEXT $username, \LONG_TEXT $allow2, \LONG_TEXT $allow2_groups, \LONG_TEXT $disallow2, \LONG_TEXT $disallow2_groups) : \tempcode

Parameters

$is_made_by_me

boolean

Whether the room is being made as a private room by the current member

$room_name

\SHORT_TEXT

The room name

$welcome

\LONG_TEXT

The welcome message

$username

\SHORT_TEXT

The owner username

$allow2

\LONG_TEXT

The comma-separated list of users that may access it (blank: no restriction)

$allow2_groups

\LONG_TEXT

The comma-separated list of usergroups that may access it (blank: no restriction)

$disallow2

\LONG_TEXT

The comma-separated list of users that may NOT access it (blank: no restriction)

$disallow2_groups

\LONG_TEXT

The comma-separated list of usergroups that may NOT access it (blank: no restriction)

Returns

\tempcodeThe fields

Get the id of the specified chatroom, from its room name.

get_chatroom_id(\SHORT_TEXT $room_name, boolean $must_not_be_im) : \?AUTO_LINK

Parameters

$room_name

\SHORT_TEXT

The name of the chatroom

$must_not_be_im

boolean

Make sure the room is not an IM room. If it is an IM room, pretend it does not exist.

Returns

\?AUTO_LINKThe ID of the chatroom (NULL: no such chat room)

Get the textual name of the specified chatroom, from its room id.

get_chatroom_name(\AUTO_LINK $room_id, boolean $allow_null) : \?SHORT_TEXT

Parameters

$room_id

\AUTO_LINK

The room ID

$allow_null

boolean

Allow the chatroom to not be found (i.e. don't die if it can't be)

Returns

\?SHORT_TEXTThe room name (NULL: not found)

Get the people who have posted a message in the specified room within the last x minutes (defaults to five).

get_chatters_in_room(\?AUTO_LINK $room_id) : array

Note that this function performs no pruning- the chat lobby will do that. It does do an activity time-range select though.

Parameters

$room_id

\?AUTO_LINK

The room ID (NULL: lobby)

Returns

arrayA map of members in the room. User ID=>Username

Get some template code showing the number of chatters in a room.

get_chatters_in_room_tpl(array $users) : \tempcode

Parameters

$users

array

A mapping (user=>username) of the chatters in the room

Returns

\tempcodeThe Tempcode

Get the list of all available chat sound effects.

get_effect_set(boolean $only_overridable) : \map

Parameters

$only_overridable

boolean

Map to NULL if it is not overridable.

Returns

\mapAll available sound effects (mapping between base code, and actual code).

Get a list of template mappings for the current member, between sound effect IDs and the URLs to the mp3 fiels.

get_effect_settings(boolean $full_urls, \?MEMBER $for_member, boolean $all_members) : array

Parameters

$full_urls

boolean

Whether to use full URLs in the mappings.

$for_member

\?MEMBER

Get settings overridden for this specific member (NULL: global settings).

$all_members

boolean

Get global settings and settings overridden for all members (if this is true we'd expect $for_member to be NULL).

Returns

arrayThe template mappings.

Get the total number of chat posts in all the chatrooms.

get_num_chatposts() : integer

Returns

integerThe number of chat posts in the database

Get the number of chatrooms in the database.

get_num_chatrooms() : integer

By default, there is only one, but more may be added via the admin panel.

Returns

integerThe number of chatrooms in the database

Get the number of people using the chat system at the moment.

get_num_chatters() : integer

Note that this is intentionally different from 'users online' even if site wide IM is enabled- it has a 60 second timeout, so it really is active people.

Returns

integerThe number of people on the chat system

Prune timed-out private chatrooms.

handle_chatroom_pruning(array $row) : boolean

Parameters

$row

array

The row of the chat room to possibly prune

Returns

booleanWhether the room was pruned

Standard code module initialisation function.

init__chat() 

Find whether a member is a moderator of a chat room.

is_chat_moderator(\MEMBER $member_id, \AUTO_LINK $room_id, \?MEMBER $room_owner) : boolean

Parameters

$member_id

\MEMBER

Member ID

$room_id

\AUTO_LINK

Room ID

$room_owner

\?MEMBER

Room owner (NULL: none)

Returns

booleanWhether the member is a moderator of the chat room

Find if a member is befriended by the current member.

member_befriended(\MEMBER $member_id) : boolean

Parameters

$member_id

\MEMBER

The member being checked

Returns

booleanWhether the member is befriended

High-level messages script handling

messages_script() 

Takes a comma-separated list of usernames, split it up, convert all the usernames to IDs, and put it all back together again.

parse_allow_list_input(string $_allow) : string

Parameters

$_allow

string

A comma-separated list of usernames

Returns

stringA comma-separated list of member IDs

Read in chat permission fields, from the complex posted data.

read_in_chat_perm_fields() : array

Returns

arrayA tuple of permission fields

Outputs the shoutbox iframe.

shoutbox_script(boolean $ret, \?AUTO_LINK $room_id, \?integer $num_messages) : \?object

Parameters

$ret

boolean

Whether to get the output instead of outputting it directly

$room_id

\?AUTO_LINK

Chat room ID (NULL: read from environment)

$num_messages

\?integer

The maximum number of messages to show (NULL: read from environment)

Returns

\?objectOutput (NULL: outputted it already)

Constants

 

CHAT_ACTIVITY_PRUNE

CHAT_ACTIVITY_PRUNE 

 

CHAT_ACTIVITY_PRUNE

CHAT_ACTIVITY_PRUNE 

 

CHAT_BACKLOG_TIME

CHAT_BACKLOG_TIME 

 

CHAT_EVENT_PRUNE

CHAT_EVENT_PRUNE