1.1 --- a/plugins/include/usermessages.inc	Fri Feb 16 19:12:27 2007 +0000
     1.2 +++ b/plugins/include/usermessages.inc	Fri Feb 16 20:07:40 2007 +0000
     1.3 @@ -39,24 +39,28 @@
     1.4  /**
     1.5   * Starts a usermessage (network message).
     1.6   * @note Only one message can be active at a time.
     1.7 + * @note It is illegal to send any message while a non-intercept hook is in progress.
     1.8   *
     1.9   * @param msgname		Message name to start.
    1.10   * @param clients		Array containing player indexes to broadcast to.
    1.11   * @param numClients	Number of players in the array.
    1.12   * @return				A handle to a bf_write bit packing structure, or
    1.13   *						INVALID_HANDLE on failure.
    1.14 + * @error				Invalid message name or unable to start a message.
    1.15   */
    1.16  native Handle:StartMessage(String:msgname[], clients[], numClients, flags);
    1.17  
    1.18  /**
    1.19   * Starts a usermessage (network message).
    1.20   * @note Only one message can be active at a time.
    1.21 + * @note It is illegal to send any message while a non-intercept hook is in progress.
    1.22   *
    1.23   * @param msg			Message index to start.
    1.24   * @param clients		Array containing player indexes to broadcast to.
    1.25   * @param numClients	Number of players in the array.
    1.26   * @return				A handle to a bf_write bit packing structure, or
    1.27   *						INVALID_HANDLE on failure.
    1.28 + * @error				Invalid message name or unable to start a message.
    1.29   */
    1.30  native Handle:StartMessageEx(UserMsg:msg, clients[], numClients, flags);
    1.31  
    1.32 @@ -68,7 +72,72 @@
    1.33  native EndMessage();
    1.34  
    1.35  /**
    1.36 + * @brief Called when a message is hooked
    1.37 + *
    1.38 + * @param msg_id		Message index.
    1.39 + * @param players		Array containing player indexes.
    1.40 + * @param playersNum	Number of players in the array.
    1.41 + * @param reliable		True if message is reliable, false otherwise.
    1.42 + * @param init			True if message is an initmsg, false otherwise.
    1.43 + * @return				Ignored for normal hooks.  For intercept hooks, false blocks 
    1.44 + *						the message from being sent, and true continues.
    1.45 + */
    1.46 +functag MsgHook bool:public(UserMsg:msg_id, Handle:bf, const players[], playersNum, bool:reliable, bool:init);
    1.47 +
    1.48 +/**
    1.49 + * @brief Hooks a user message.
    1.50 + *
    1.51 + * @param msg_id		Message index.
    1.52 + * @param hook			Function to use as a hook.
    1.53 + * @param intercept		If intercept is true, message will be fully intercepted,
    1.54 + * 						allowing the user to block the message.  Otherwise,
    1.55 + *						the hook is normal and ignores the return value.
    1.56 + * @noreturn
    1.57 + * @error				Invalid message index.
    1.58 + */
    1.59 +native HookUserMessage(UserMsg:msg_id, MsgHook:hook, bool:intercept=false);
    1.60 +
    1.61 +/**
    1.62 + * @brief Removes one usermessage hook.
    1.63 + *
    1.64 + * @param msg_id		Message index.
    1.65 + * @param hook			Function used for the hook.
    1.66 + * @param intercept		Specifies whether the hook was an intercept hook or not.
    1.67 + * @noreturn
    1.68 + * @error				Invalid message index.
    1.69 + */
    1.70 +native UnHookUserMessage(UserMsg:msg_id, MsgHook:hook, bool:intercept=false);
    1.71 +
    1.72 +/**
    1.73 + * @brief Called when a message is finished sending.
    1.74 + *
    1.75 + * @param msg_id		Message index.
    1.76 + */
    1.77 +functag MsgSentNotify public(UserMsg:msg_id);
    1.78 +
    1.79 +/**
    1.80 + * @brief Notifies when a message has finished sending.
    1.81 + *
    1.82 + * @param msg_id		Message index.
    1.83 + * @param notify		Notification function.
    1.84 + * @noreturn
    1.85 + * @error				Invalid message index.
    1.86 + */
    1.87 +native NotifyUserMessage(UserMsg:msg_id, MsgSentNotify:notify);
    1.88 +
    1.89 +/**
    1.90 + * @brief Removes a user message notification.
    1.91 + *
    1.92 + * @param msg_id		Message index.
    1.93 + * @param notify		Notification function.
    1.94 + * @noreturn
    1.95 + * @error				Invalid message index.
    1.96 + */
    1.97 +native RemoveNotifyUserMessage(UserMsg:msg_id, MsgSentNotify:notify);
    1.98 +
    1.99 +/**
   1.100   * Starts a usermessage (network message) that broadcasts to all clients.
   1.101 + * @note See StartMessage or StartMessageEx().
   1.102   *
   1.103   * @param msgname		Message name to start.
   1.104   * @param flags			Optional flags to set.
   1.105 @@ -92,6 +161,7 @@
   1.106  
   1.107  /**
   1.108   * Starts a simpler usermessage (network message) for one client.
   1.109 + * @note See StartMessage or StartMessageEx().
   1.110   *
   1.111   * @param msgname		Message name to start.
   1.112   * @param client		Client to send to.