File /obj/handlers/group_handler.c

Written by Tape

Started February 99

Includes

Class Index

• group

Method index

• add_invite(string, object, int)
  This function allows you to add a person to the invite array of a group.
• add_member(string, object)
  This function allows you to add a member to a group.
• broadcast_to_groups(string *, string)
  With this function you can broadcaster a message to all or some of the groups currently active.
• create_group(string)
  This function allows you to create a new group.
• create_request(string, string)
  This function adds a request to the handler and is used by the group command to allow players to add grouping requests.
• disband_group(string, mixed)
  This function does a clean removal of a group from the handler.
• invitations_to(string)
  This function lists all invitations to a particular group.
• is_group(string)
  This function checks if such a group exists at the moment.
• is_invited(string, object)
  This function allows you to check whether an invitation for a person is pending in a specific group.
• is_member(string, object)
  This function allows you to check whether a person is a member of a group.
• leader_of(string)
  This function returns the person who is currently leading the group, if any.
• members_of(string)
  This function returns all the members of a group.
• notify_group(string, object, mixed)
  This function broadcasts a message to the group's channel using the broadcaster handler.
• query_group_short(string)
  This returns the short description of a group.
• query_groups()
  This returns the names of all groups currently in the database.
• query_request_desc(string)
  This returns the description of a grouping request.
• query_requests()
  This returns the names of all requests currently in the database.
• query_start_time(string)
  This function returns the time when the group was created.
• remove_group(string)
  This function removes a group from the handler and is only used internally.
• remove_invite(string, object)
  This function allows you to remove an invite of a person from a group.
• remove_member(string, object, string)
  This function allows you to remove a person from a group.
• remove_request(string)
  This function removes a request from the handler and is used by the group command to allow players to remove grouping requests.
• rename_group(string, string, string)
  This method renames the group.
• set_group_short(string, string)
  This sets the short description of a group.
• set_leader(string, object, object)
  This function allows you to set a new leader for the group.
• short_to_name(string)
  This function concatenates the short of a group to a valid name that can then be used with create_group().
• shuffle_new_leader(string, int, object *)
  This function allows you to choose a new leader for the group in a variety of ways.

Public Functions

add_invite

int add_invite(string name,
               object person,
               int flag)

This function allows you to add a person to the invite array of a group. Only invited people are allowed to join a group. If the call succeeds, an internal call_out is started which runs out after INVITE_TIMEOUT seconds and removes the person from the array.

Parameters:
name - the name of the group
person - the person we're inviting
flag - set to 1 if you don't want the auto-removal of the invite

Returns:
1 on success, 0 if the group doesn't exist or the person is already invited

See also:
/include/group_handler.h

add_member

int add_member(string name,
               object person)

This function allows you to add a member to a group.

Parameters:
name - the name of the group
person - the person you're adding

Returns:
1 on success, 0 if the group doesn't exist or person is already a member

broadcast_to_groups

void broadcast_to_groups(string * name,
                         string message)

With this function you can broadcaster a message to all or some of the groups currently active. It will not include your name, so make sure you identify yourself if necessary. If "name" is empty or 0, the message will be broadcasted to all groups.

Parameters:
name - a string array with names of groups

create_group

int create_group(string name)

This function allows you to create a new group. Note that the name of the group shouldn't be just any name. It should first be filtered through short_to_name(). The short, set with set_group_short() can be set to anything. The "name" of a group is mostly used internally to query and set stuff in the handler. The short is visible to players.

Parameters:
name - the name of the new group
founder - points to the thing creating the group

Returns:
1 on success, 0 if the group already exists

See also:
short_to_name() and set_group_short()

create_request

int create_request(string desc,
                   string name)

This function adds a request to the handler and is used by the group command to allow players to add grouping requests.

Parameters:
desc - a brief description of the grouping request
player - the player ob whose request is being made

Returns:
1 on success (currently always)

See also:
remove_request()

disband_group

varargs void disband_group(string name,
                           mixed message)

This function does a clean removal of a group from the handler. If a message is specified, it is broadcasted to the group before all members are removed.

Parameters:
name - the name of the group to be disbanded
message - message to be broadcasted, if any

See also:
remove_group()

invitations_to

object * invitations_to(string name)

This function lists all invitations to a particular group.

Parameters:
name - the name of the group

Returns:
objects who have been invited to the group

is_group

int is_group(string group)

This function checks if such a group exists at the moment.

Parameters:
group - the name of the group

Returns:
1 if the group exists, 0 otherwise

is_invited

int is_invited(string name,
               object person)

This function allows you to check whether an invitation for a person is pending in a specific group.

Parameters:
name - the name of the group
person - the person to be checked

Returns:
1 if such an invitation exists, 0 if not

is_member

int is_member(string name,
              object person)

This function allows you to check whether a person is a member of a group.

Parameters:
name - the name of the group
person - the person you want to check for membership

Returns:
1 if he is a member, 0 if he isn't (or the group doesn't exist)

leader_of

object leader_of(string name)

This function returns the person who is currently leading the group, if any.

Parameters:
name - the name of the group

Returns:
the object pointing to the leader, 0 if none

members_of

object * members_of(string name)

This function returns all the members of a group.

Parameters:
name - the name of the group

Returns:
an object * of the members

notify_group

void notify_group(string name,
                  object broadcaster,
                  mixed message)

This function broadcasts a message to the group's channel using the broadcaster handler. The first argument specifies the group's name (not short), which also acts as the channel name. The second argument is the object doing the broadcasting. The third argument varies. It can either be a simple string, in which case that string is printed as the message. It can also be a two-element string array. The first element is printed only to the object specified in the second argument. The second element is printed to everyone else.

Parameters:
name - the name of the group
object - person or object doing the broadcasting
message - the message to be broadcasted

query_group_short

string query_group_short(string name)

This returns the short description of a group.

Parameters:
name - the name of the group

Returns:
the short of the group

query_groups

string * query_groups()

This returns the names of all groups currently in the database.

Returns:
the names of all groups in database

query_request_desc

string query_request_desc(string name)

This returns the description of a grouping request.

Parameters:
name - the name of the player

Returns:
the description of the grouping request

query_requests

string * query_requests()

This returns the names of all requests currently in the database.

Returns:
the names of all players with requests in database

query_start_time

int query_start_time(string name)

This function returns the time when the group was created.

Parameters:
name - the name of the group

Returns:
the time when the group was created

remove_group

int remove_group(string name)

This function removes a group from the handler and is only used internally. No notification of this is given to players, and no cleanup is done on their part. If you want to force the deletion of a group, use disband_group() instead.

Parameters:
name - name of the group to be disbanded

Returns:
1 on success, 0 if group doesn't exist

See also:
disband_group()

remove_invite

int remove_invite(string name,
                  object person)

This function allows you to remove an invite of a person from a group.

Parameters:
name - the name of the group
person - the person you want to remove

Returns:
1 on success, 0 if group doesn't exist or person hasn't been invited

remove_member

int remove_member(string name,
                  object person,
                  string reason)

This function allows you to remove a person from a group.

Parameters:
name - the name of the group
person - the person you want removed

Returns:
1 on success, 0 if group doesn't exist or person isn't a member

remove_request

int remove_request(string name)

This function removes a request from the handler and is used by the group command to allow players to remove grouping requests.

Parameters:
player - the player ob whose request is being withdrawn

Returns:
1 on success, 0 if request doesn't exist

See also:
create_request()

rename_group

int rename_group(string group,
                 string new_group,
                 string new_group_short)

This method renames the group.

Parameters:
group - the old group name
new_group - the new group name

set_group_short

int set_group_short(string name,
                    string short_desc)

This sets the short description of a group.

Parameters:
name - the name of the group
short_desc - the short of the group

Returns:
1 on success, 0 if group doesn't exist

set_leader

varargs int set_leader(string name,
                       object person,
                       object appointer)

This function allows you to set a new leader for the group.

Parameters:
name - the name of the group
person - the new leader
appointer - if this != 0, group is told he set the new leader

Returns:
1 on success, 0 if the group doesn't exist

short_to_name

string short_to_name(string short)

This function concatenates the short of a group to a valid name that can then be used with create_group(). The function will also return invalid if a channel with such a name exists in the broadcaster.

Parameters:
short - the short of the group

Returns:
the name of the group, or "" if invalid

shuffle_new_leader

varargs object shuffle_new_leader(string group,
                                  int way,
                                  object * exclude)

This function allows you to choose a new leader for the group in a variety of ways. It only includes players who are interactive().

Parameters:
group - the name of the group
way - 0 for random (no other ways present atm)
exclude - an object array of members to exclude from the start

Returns:
an object pointing to the new leader, or 0

Classes

• group

  class group {
                int start_time;
                string short;
                string leader_name;
                object leader;
                object * members;
                object * invited;
  }