Functions

Add a chatroom.

add_chatroom(\SHORT_TEXT $welcome, \SHORT_TEXT $room_name, \MEMBER $room_owner, \LONG_TEXT $allow2, \LONG_TEXT $allow2_groups, \LONG_TEXT $disallow2, \LONG_TEXT $disallow2_groups, \LANGUAGE_NAME $room_language, \BINARY $is_im = 0) : \AUTO_LINK
package chat

Parameters

$welcome

\SHORT_TEXT

The welcome message

$room_name

\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)

$room_language

\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 = null
package chat

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) 
package chat

Parameters

$blocker

\MEMBER

The member unblocking

$blocked

\MEMBER

The member being unblocked

Get an array of all the chatrooms.

chat_get_all_rooms() : array
package chat

Returns

arrayAn array of all the chatrooms

Get a multidimensional array of the content of the specified chatroom. It automatically parses for Comcode, chatcode, banned words, emoticons, 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.

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

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.

package chat

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() 
package chat

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

chat_poller() 
package chat

Enter a message into the database for the specified room, and with the specified parameters. The message is filtered for banned words, and is compressed into a Tempcode storage format.

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

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) 
package chat

Parameters

$room_id

\AUTO_LINK

Room ID (or -1 if all rooms)

Ban a member from a chatroom.

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

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) 
package chat

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. not away).

chatter_active(\MEMBER $member_id, \?AUTO_LINK $room_id = null) : boolean
package chat

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 = false, \?MEMBER $member_id = null, boolean $must_be_explicit = false) : boolean
package chat

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() 
package chat

Delete chat messages.

delete_chat_messages(array $where) 
package chat

Parameters

$where

array

Where query to specify what to delete

Delete a chatroom.

delete_chatroom(\AUTO_LINK $id) 
package chat

Parameters

$id

\AUTO_LINK

The chat room ID

Delete all messages in a chatroom.

delete_chatroom_messages(\AUTO_LINK $id) 
package chat

Parameters

$id

\AUTO_LINK

The chat room ID

Edit a chatroom.

edit_chatroom(\AUTO_LINK $id, \SHORT_TEXT $welcome, \SHORT_TEXT $room_name, \MEMBER $room_owner, \LONG_TEXT $allow2, \LONG_TEXT $allow2_groups, \LONG_TEXT $disallow2, \LONG_TEXT $disallow2_groups, \LANGUAGE_NAME $room_language) 
package chat

Parameters

$id

\AUTO_LINK

The chat room ID

$welcome

\SHORT_TEXT

The welcome message

$room_name

\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)

$room_language

\LANGUAGE_NAME

The room language

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

enter_chat_lobby() 
package chat

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
package chat

Parameters

$people

string

Comma-separated people list

Returns

stringFiltered comma-separated people list

Add a friend.

friend_add(\MEMBER $likes, \MEMBER $liked, \?TIME $time = null
package chat

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) 
package chat

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
package chat

Returns

\TempcodeTemplate to set up chat sound effects.

Get form fields for adding/editing a chatroom.

get_chatroom_fields(\?AUTO_LINK $id = null, boolean $is_made_by_me = false, \SHORT_TEXT $room_name = '', \LONG_TEXT $welcome = '', \SHORT_TEXT $username = '', \LONG_TEXT $allow2 = '', \LONG_TEXT $allow2_groups = '', \LONG_TEXT $disallow2 = '', \LONG_TEXT $disallow2_groups = '') : array
package chat

Parameters

$id

\?AUTO_LINK

The chat room ID (null: new)

$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

arrayA pair: The input fields, Hidden fields

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

get_chatroom_id(\SHORT_TEXT $room_name, boolean $must_not_be_im = false) : \?AUTO_LINK
package chat

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 = false) : \?SHORT_TEXT
package chat

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). Note that this function performs no pruning- the chat lobby will do that. It does do an activity time-range select though.

get_chatters_in_room(\?AUTO_LINK $room_id) : array
package chat

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
package chat

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 = false) : \map
package chat

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 = false, \?MEMBER $for_member = null, boolean $all_members = false) : array
package chat

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
package chat

Returns

integerThe number of chat posts in the database

Get the number of chatrooms in the database. By default, there is only one, but more may be added via the admin panel.

get_num_chatrooms() : integer
package chat

Returns

integerThe number of chatrooms in the database

Get the number of people using the chat system at the moment. 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.

get_num_chatters() : integer
package chat

Returns

integerThe number of people on the chat system

Prune timed-out private chatrooms.

handle_chatroom_pruning(array $row) : boolean
package chat

Parameters

$row

array

The row of the chat room to possibly prune

Returns

booleanWhether the room was pruned

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
package chat

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
package chat

Parameters

$member_id

\MEMBER

The member being checked

Returns

booleanWhether the member is befriended

High-level messages script handling

messages_script() 
package chat

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
package chat

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
package chat

Returns

arrayA tuple of permission fields

Get Tempcode for a chat room 'feature box' for the given row

render_chat_box(array $row, \ID_TEXT $zone = '_SEARCH', boolean $give_context = true, \ID_TEXT $guid = '') : \Tempcode
package chat

Parameters

$row

array

The database field row of it

$zone

\ID_TEXT

The zone to use

$give_context

boolean

Whether to include context (i.e. say WHAT this is, not just show the actual content)

$guid

\ID_TEXT

Overridden GUID to send to templates (blank: none)

Returns

\TempcodeA box for it, linking to the full page

Outputs the shoutbox iframe.

shoutbox_script(boolean $ret = false, \?AUTO_LINK $room_id = null, \?integer $num_messages = null) : \?object
package chat

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)

Show IM contacts, with online/offline status and clickability to initiate IM sessions.

show_im_contacts(\?MEMBER $member_id = null, boolean $simpler = false, \?integer $max = null) : \Tempcode
package chat

Parameters

$member_id

\?MEMBER

The member ID (null: current user).

$simpler

boolean

Whether to show a simpler, more compact, UI.

$max

\?integer

Maximum to show (null: default).

Returns

\TempcodeThe contact UI.

Constants

 

CHAT_ACTIVITY_PRUNE

CHAT_ACTIVITY_PRUNE = 25 
package chat
 

CHAT_ACTIVITY_PRUNE

CHAT_ACTIVITY_PRUNE = 25 
package chat
 

CHAT_ACTIVITY_PRUNE

CHAT_ACTIVITY_PRUNE = 25 
package chat
 

CHAT_BACKLOG_TIME

CHAT_BACKLOG_TIME = 60 * 5 
package chat
 

CHAT_EVENT_PRUNE

CHAT_EVENT_PRUNE = 60 * 60 * 24 
package chat