[an error occurred while processing this directive]
[<a href="index.shtml">Package Index</a></code> | <a href="index_std.shtml">Mudlib Index</a></code> | <a href="index_eff.shtml">Effect Index</a></code>]<br><h2>File /obj/handlers/group_handler.c</h2>
This is the group handler.  It does all the handling of
player-run adventuring groups, but not alone.  It's
accompanied by the group commands, effect and shadow.
For paths to these files, consult /include/group_handler.h

This system owes its design first and foremost to the irreplaceable
Ceres who wrote the original system.  Next come all the valuable
Creators who shared their knowledge of LPC.  Last but not least
are the countless playtesters who dedicated their time and worked
out all (or most of) the kinks and provided feedback and suggestions.

So give 'em all a big hug.
<p>Written by Tape<p>Started February 99
<h2>Includes</h2>
This class includes the following files /include/player_handler.h, /include/command.h, /include/login_handler.h, /include/group_handler.h and /include/broadcaster.h<h2>Class Index</h2>
<ul><li><a href="#class_group">group</a>
</ul><h2>Method index</h2>
<ul>
<li><a href="#add_invite">add_invite</a>(string, object, int)<br/>
This function allows you to add a person to the invite array
of a group.
<li><a href="#add_member">add_member</a>(string, object)<br/>
This function allows you to add a member to a group.
<li><a href="#broadcast_to_groups">broadcast_to_groups</a>(string *, string)<br/>
With this function you can broadcaster a message to all or
some of the groups currently active.
<li><a href="#create_group">create_group</a>(string)<br/>
This function allows you to create a new group.
<li><a href="#create_request">create_request</a>(string, string)<br/>
This function adds a request to the handler and is used by the group
command to allow players to add grouping requests.
<li><a href="#disband_group">disband_group</a>(string, mixed)<br/>
This function does a clean removal of a group from the handler.
<li><a href="#invitations_to">invitations_to</a>(string)<br/>
This function lists all invitations to a particular group.
<li><a href="#is_group">is_group</a>(string)<br/>
This function checks if such a group exists at the moment.
<li><a href="#is_invited">is_invited</a>(string, object)<br/>
This function allows you to check whether an invitation for a
person is pending in a specific group.
<li><a href="#is_member">is_member</a>(string, object)<br/>
This function allows you to check whether a person is a member
of a group.
<li><a href="#leader_of">leader_of</a>(string)<br/>
This function returns the person who is currently
leading the group, if any.
<li><a href="#members_of">members_of</a>(string)<br/>
This function returns all the members of a group.
<li><a href="#notify_group">notify_group</a>(string, object, mixed)<br/>
This function broadcasts a message to the group's channel using
the broadcaster handler.
<li><a href="#query_group_short">query_group_short</a>(string)<br/>
This returns the short description of a group.
<li><a href="#query_groups">query_groups</a>()<br/>
This returns the names of all groups currently in the database.
<li><a href="#query_request_desc">query_request_desc</a>(string)<br/>
This returns the description of a grouping request.
<li><a href="#query_requests">query_requests</a>()<br/>
This returns the names of all requests currently in the database.
<li><a href="#query_start_time">query_start_time</a>(string)<br/>
This function returns the time when the group was created.
<li><a href="#remove_group">remove_group</a>(string)<br/>
This function removes a group from the handler and is only used
internally.
<li><a href="#remove_invite">remove_invite</a>(string, object)<br/>
This function allows you to remove an invite of a person from
a group.
<li><a href="#remove_member">remove_member</a>(string, object, string)<br/>
This function allows you to remove a person from a group.
<li><a href="#remove_request">remove_request</a>(string)<br/>
This function removes a request from the handler and is used by the group
command to allow players to remove grouping requests.
<li><a href="#rename_group">rename_group</a>(string, string, string)<br/>
This method renames the group.
<li><a href="#set_group_short">set_group_short</a>(string, string)<br/>
This sets the short description of a group.
<li><a href="#set_leader">set_leader</a>(string, object, object)<br/>
This function allows you to set a new leader for the group.
<li><a href="#short_to_name">short_to_name</a>(string)<br/>
This function concatenates the short of a group to a valid name
that can then be used with create_group().
<li><a href="#shuffle_new_leader">shuffle_new_leader</a>(string, int, object *)<br/>
This function allows you to choose a new leader for the group
in a variety of ways.
</ul>
<h2>Public Functions</h2>
These are functions that everyone can access.<p>
<dl>
<dt class="autodocfuncname"><a name="add_invite">
add_invite</a><pre class="autodocfuncdef">
int add_invite(string name,
               object person,
               int flag)
</pre><dd><br />
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.
<br />
<br /><dl>
<dd><b>Parameters:</b><br />
name - the name of the group<br />
person - the person we're inviting<br />
flag - set to 1 if you don't want the auto-removal of the invite
<br />
<br />
<dd><b>Returns:</b>
<br />1 on success, 0 if the group doesn't exist or the person is
   already invited
<br /><br />
<dd><b>See also:</b>
<br />/include/group_handler.h
<br /><br /><br /></dl>

<dt class="autodocfuncname"><a name="add_member">
add_member</a><pre class="autodocfuncdef">
int add_member(string name,
               object person)
</pre><dd><br />
This function allows you to add a member to a group.
<br />
<br /><dl>
<dd><b>Parameters:</b><br />
name - the name of the group<br />
person - the person you're adding<br />
<br />
<dd><b>Returns:</b>
<br />1 on success, 0 if the group doesn't exist or person is
   already a member
<br /><br />
<br /></dl>

<dt class="autodocfuncname"><a name="broadcast_to_groups">
broadcast_to_groups</a><pre class="autodocfuncdef">
void broadcast_to_groups(string * name,
                         string message)
</pre><dd><br />
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.
<br />
<br /><dl>
<dd><b>Parameters:</b><br />
name - a string array with names of groups<br />
<br />
<br /></dl>

<dt class="autodocfuncname"><a name="create_group">
create_group</a><pre class="autodocfuncdef">
int create_group(string name)
</pre><dd><br />
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.
<br />
<br /><dl>
<dd><b>Parameters:</b><br />
name - the name of the new group<br />
founder - points to the thing creating the group
<br />
<br />
<dd><b>Returns:</b>
<br />1 on success, 0 if the group already exists
<br /><br />
<dd><b>See also:</b>
<br /><a href="#short_to_name">short_to_name()</a> and <a href="#set_group_short">set_group_short()
</a><br /><br /><br /></dl>

<dt class="autodocfuncname"><a name="create_request">
create_request</a><pre class="autodocfuncdef">
int create_request(string desc,
                   string name)
</pre><dd><br />
This function adds a request to the handler and is used by the group
command to allow players to add grouping requests.
<br />
<br /><dl>
<dd><b>Parameters:</b><br />
desc - a brief description of the grouping request<br />
player - the player ob whose request is being made
<br />
<br />
<dd><b>Returns:</b>
<br />1 on success (currently always)
<br /><br />
<dd><b>See also:</b>
<br /><a href="#remove_request">remove_request()
</a><br /><br /><br /></dl>

<dt class="autodocfuncname"><a name="disband_group">
disband_group</a><pre class="autodocfuncdef">
varargs void disband_group(string name,
                           mixed message)
</pre><dd><br />
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.
<br />
<br /><dl>
<dd><b>Parameters:</b><br />
name - the name of the group to be disbanded<br />
message - message to be broadcasted, if any<br />
<br />
<dd><b>See also:</b>
<br /><a href="#remove_group">remove_group()
</a><br /><br /><br /></dl>

<dt class="autodocfuncname"><a name="invitations_to">
invitations_to</a><pre class="autodocfuncdef">
object * invitations_to(string name)
</pre><dd><br />
This function lists all invitations to a particular group.<br />
<br /><dl>
<dd><b>Parameters:</b><br />
name - the name of the group<br />
<br />
<dd><b>Returns:</b>
<br />objects who have been invited to the group
<br /><br />
<br /></dl>

<dt class="autodocfuncname"><a name="is_group">
is_group</a><pre class="autodocfuncdef">
int is_group(string group)
</pre><dd><br />
This function checks if such a group exists at the moment.
<br />
<br /><dl>
<dd><b>Parameters:</b><br />
group - the name of the group<br />
<br />
<dd><b>Returns:</b>
<br />1 if the group exists, 0 otherwise
<br /><br />
<br /></dl>

<dt class="autodocfuncname"><a name="is_invited">
is_invited</a><pre class="autodocfuncdef">
int is_invited(string name,
               object person)
</pre><dd><br />
This function allows you to check whether an invitation for a
person is pending in a specific group.
<br />
<br /><dl>
<dd><b>Parameters:</b><br />
name - the name of the group<br />
person - the person to be checked
<br />
<br />
<dd><b>Returns:</b>
<br />1 if such an invitation exists, 0 if not
<br /><br />
<br /></dl>

<dt class="autodocfuncname"><a name="is_member">
is_member</a><pre class="autodocfuncdef">
int is_member(string name,
              object person)
</pre><dd><br />
This function allows you to check whether a person is a member
of a group.
<br />
<br /><dl>
<dd><b>Parameters:</b><br />
name - the name of the group<br />
person - the person you want to check for membership
<br />
<br />
<dd><b>Returns:</b>
<br />1 if he is a member, 0 if he isn't (or the group doesn't exist)

<br /><br />
<br /></dl>

<dt class="autodocfuncname"><a name="leader_of">
leader_of</a><pre class="autodocfuncdef">
object leader_of(string name)
</pre><dd><br />
This function returns the person who is currently
leading the group, if any.
<br />
<br /><dl>
<dd><b>Parameters:</b><br />
name - the name of the group<br />
<br />
<dd><b>Returns:</b>
<br />the object pointing to the leader, 0 if none
<br /><br />
<br /></dl>

<dt class="autodocfuncname"><a name="members_of">
members_of</a><pre class="autodocfuncdef">
object * members_of(string name)
</pre><dd><br />
This function returns all the members of a group.<br />
<br /><dl>
<dd><b>Parameters:</b><br />
name - the name of the group<br />
<br />
<dd><b>Returns:</b>
<br />an object * of the members
<br /><br />
<br /></dl>

<dt class="autodocfuncname"><a name="notify_group">
notify_group</a><pre class="autodocfuncdef">
void notify_group(string name,
                  object broadcaster,
                  mixed message)
</pre><dd><br />
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.
<br />
<br /><dl>
<dd><b>Parameters:</b><br />
name - the name of the group<br />
object - person or object doing the broadcasting<br />
message - the message to be broadcasted

<br />
<br />
<br /></dl>

<dt class="autodocfuncname"><a name="query_group_short">
query_group_short</a><pre class="autodocfuncdef">
string query_group_short(string name)
</pre><dd><br />
This returns the short description of a group.<br />
<br /><dl>
<dd><b>Parameters:</b><br />
name - the name of the group<br />
<br />
<dd><b>Returns:</b>
<br />the short of the group
<br /><br />
<br /></dl>

<dt class="autodocfuncname"><a name="query_groups">
query_groups</a><pre class="autodocfuncdef">
string * query_groups()
</pre><dd><br />
This returns the names of all groups currently in the database.<br />
<br /><dl>
<dd><b>Returns:</b>
<br />the names of all groups in database
<br /><br />
<br /></dl>

<dt class="autodocfuncname"><a name="query_request_desc">
query_request_desc</a><pre class="autodocfuncdef">
string query_request_desc(string name)
</pre><dd><br />
This returns the description of a grouping request.<br />
<br /><dl>
<dd><b>Parameters:</b><br />
name - the name of the player<br />
<br />
<dd><b>Returns:</b>
<br />the description of the grouping request
<br /><br />
<br /></dl>

<dt class="autodocfuncname"><a name="query_requests">
query_requests</a><pre class="autodocfuncdef">
string * query_requests()
</pre><dd><br />
This returns the names of all requests currently in the database.<br />
<br /><dl>
<dd><b>Returns:</b>
<br />the names of all players with requests in database
<br /><br />
<br /></dl>

<dt class="autodocfuncname"><a name="query_start_time">
query_start_time</a><pre class="autodocfuncdef">
int query_start_time(string name)
</pre><dd><br />
This function returns the time when the group was created.<br />
<br /><dl>
<dd><b>Parameters:</b><br />
name - the name of the group<br />
<br />
<dd><b>Returns:</b>
<br />the time when the group was created
<br /><br />
<br /></dl>

<dt class="autodocfuncname"><a name="remove_group">
remove_group</a><pre class="autodocfuncdef">
int remove_group(string name)
</pre><dd><br />
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.
<br />
<br /><dl>
<dd><b>Parameters:</b><br />
name - name of the group to be disbanded<br />
<br />
<dd><b>Returns:</b>
<br />1 on success, 0 if group doesn't exist<br /><br />
<dd><b>See also:</b>
<br /><a href="#disband_group">disband_group()
</a><br /><br /><br /></dl>

<dt class="autodocfuncname"><a name="remove_invite">
remove_invite</a><pre class="autodocfuncdef">
int remove_invite(string name,
                  object person)
</pre><dd><br />
This function allows you to remove an invite of a person from
a group.
<br />
<br /><dl>
<dd><b>Parameters:</b><br />
name - the name of the group<br />
person - the person you want to remove
<br />
<br />
<dd><b>Returns:</b>
<br />1 on success, 0 if group doesn't exist or person hasn't been
   invited
<br /><br />
<br /></dl>

<dt class="autodocfuncname"><a name="remove_member">
remove_member</a><pre class="autodocfuncdef">
int remove_member(string name,
                  object person,
                  string reason)
</pre><dd><br />
This function allows you to remove a person from a group.
<br />
<br /><dl>
<dd><b>Parameters:</b><br />
name - the name of the group<br />
person - the person you want removed
<br />
<br />
<dd><b>Returns:</b>
<br />1 on success, 0 if group doesn't exist or person isn't a
   member
<br /><br />
<br /></dl>

<dt class="autodocfuncname"><a name="remove_request">
remove_request</a><pre class="autodocfuncdef">
int remove_request(string name)
</pre><dd><br />
This function removes a request from the handler and is used by the group
command to allow players to remove grouping requests.
<br />
<br /><dl>
<dd><b>Parameters:</b><br />
player - the player ob whose request is being withdrawn<br />
<br />
<dd><b>Returns:</b>
<br />1 on success, 0 if request doesn't exist
<br /><br />
<dd><b>See also:</b>
<br /><a href="#create_request">create_request()
</a><br /><br /><br /></dl>

<dt class="autodocfuncname"><a name="rename_group">
rename_group</a><pre class="autodocfuncdef">
int rename_group(string group,
                 string new_group,
                 string new_group_short)
</pre><dd><br />
This method renames the group.<br />
<br /><dl>
<dd><b>Parameters:</b><br />
group - the old group name<br />
new_group - the new group name
<br />
<br />
<br /></dl>

<dt class="autodocfuncname"><a name="set_group_short">
set_group_short</a><pre class="autodocfuncdef">
int set_group_short(string name,
                    string short_desc)
</pre><dd><br />
This sets the short description of a group.
<br />
<br /><dl>
<dd><b>Parameters:</b><br />
name - the name of the group<br />
short_desc - the short of the group
<br />
<br />
<dd><b>Returns:</b>
<br />1 on success, 0 if group doesn't exist
<br /><br />
<br /></dl>

<dt class="autodocfuncname"><a name="set_leader">
set_leader</a><pre class="autodocfuncdef">
varargs int set_leader(string name,
                       object person,
                       object appointer)
</pre><dd><br />
This function allows you to set a new leader for the group.
<br />
<br /><dl>
<dd><b>Parameters:</b><br />
name - the name of the group<br />
person - the new leader<br />
appointer - if this != 0, group is told he set the new leader
<br />
<br />
<dd><b>Returns:</b>
<br />1 on success, 0 if the group doesn't exist
<br /><br />
<br /></dl>

<dt class="autodocfuncname"><a name="short_to_name">
short_to_name</a><pre class="autodocfuncdef">
string short_to_name(string short)
</pre><dd><br />
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.
<br />
<br /><dl>
<dd><b>Parameters:</b><br />
short - the short of the group<br />
<br />
<dd><b>Returns:</b>
<br />the name of the group, or "" if invalid
<br /><br />
<br /></dl>

<dt class="autodocfuncname"><a name="shuffle_new_leader">
shuffle_new_leader</a><pre class="autodocfuncdef">
varargs object shuffle_new_leader(string group,
                                  int way,
                                  object * exclude)
</pre><dd><br />
This function allows you to choose a new leader for the group
in a variety of ways.  It only includes players who are
interactive().
<br />
<br /><dl>
<dd><b>Parameters:</b><br />
group - the name of the group<br />
way - 0 for random (no other ways present atm)<br />
exclude - an object array of members to exclude from the start<br />
<br />
<dd><b>Returns:</b>
<br />an object pointing to the new leader, or 0
<br /><br />
<br /></dl>

</dl>
<h2>Classes</h2>
These are nice data types for dealing with...  Data!<p>
<ul>
<li><a name="class_group">
group</a><pre>
class group {
              int start_time;
              string short;
              string leader_name;
              object leader;
              object * members;
              object * invited;
}

</pre>
</ul>
[an error occurred while processing this directive]