/drupal7/sites/all/modules/privatemsg/privatemsg.api.php - Club Drupal - Forge Centrale Marseille

root / drupal7 / sites / all / modules / privatemsg / privatemsg.api.php @ 87dbc3bf

       <?php
       /**
        * @file
        * Privatemsg API Documentation
        */
       /**
        * @mainpage Privatemsg API Documentation
        * This is the API documentation of Privatemsg.
+       *
        * - Topics:
        *  - @link api API functions @endlink
        *  - @link sql Query builder and related hooks @endlink
        *  - @link message_hooks Message hooks @endlink
        *  - @link generic_hooks Generic hooks @endlink
        *  - @link theming Theming @endlink
        *  - @link types Types of recipients @endlink
        */
       /**
        * @defgroup sql Query Builder
+       *
        * Query builder and related hooks
+       *
        * Privatemsg uses SelectQuery combined with custom tags to allow to customize
        * almost all SELECT queries. For more information about SelectQuery, see
        * http://drupal.org/developing/api/database and http://drupal.org/node/310075.
+       *
        * Arguments to a given query is stored in the metadata, with numerical keys
        * (arg_%d) according to the position of the argument.
+       *
        */
       /**
        * @addtogroup sql
        * @{
        */
       /**
        * Query to search for autocomplete usernames.
+       *
        * @param $query
        *   Query object
+       *
        * @see privatemsg_sql_autocomplete()
        * @see hook_query_alter()
        */
       function hook_query_privatemsg_autocomplete_alter($query) {
         global $user;
         $search = $query->getMetaData('arg_1');
         $names = $query->getMetaData('arg_2');
         // For example, add a join on a table where the user connections are stored
         // and specify that only users connected with the current user should be
         // loaded.
         $query->innerJoin('my_table', 'm', 'm.user1 = u.uid AND m.user2 = :user2', array(':user2' => $user->uid));
+      }
       /**
        * Display a list of threads.
+       *
        * @param $query
        *   Query object
+       *
        * @see privatemsg_sql_list()
        * @see hook_query_alter()
        */
       function hook_query_privatemsg_sql_list_alter($query) {
         $account = $query->getMetaData('arg_1');
+      }
       /**
        * Query definition to load messages of one or multiple threads.
+       *
        * @param $query
        *   Query object
+       *
        * @see privatemsg_sql_messages()
        * @see hook_query_alter()
        */
       function hook_query_privatemsg_messages_alter($query) {
         $threads = $query->getMetaData('arg_1');
         $account = $query->getMetaData('arg_2');
         $load_all = $query->getMetaData('arg_3');
+      }
       /**
        * Alter the query that loads the participants of a thread.
+       *
        * @param $query
        *   Query object
+       *
        * @see privatemsg_sql_participants()
        * @see hook_query_alter()
        */
       function hook_query_privatemsg_participants_alter($query) {
         $thread_id = $query->getMetaData('arg_1');
         $account = $query->getMetaData('arg_2');
+      }
       /**
        * Loads all unread messages of a user (only the count query is used).
+       *
        * @param $query
        *   Query object
+       *
        * @see privatemsg_sql_unread_count()
        * @see hook_query_alter()
        */
       function hook_query_privatemsg_unread_count_alter($query) {
         $account = $query->getMetaData('arg_1');
+      }
       /**
        * Alter the query that loads deleted messages to flush them.
+       *
        * @param $query
        *   Query object
+       *
        * @see privatemsg_sql_deleted()
        * @see hook_query_alter()
        */
       function hook_query_privatemsg_deleted_alter($query) {
         $days = $query->getMetaData('arg_1');
         $max = $query->getMetaData('arg_2');
+      }
       /**
        * @}
        */
       /**
        * @defgroup api API functions
+       *
        * There are two different functions to send messages.
        * Either by starting a @link privatemsg_new_thread new thread @endlink
        * or @link privatemsg_reply reply @endlink to an existing thread.
+       *
        * There is also a function which returns a link to the privatemsg new message
        * form with the recipient pre-filled if the user is allowed to.
        * privatemsg_get_link().
        */
       /**
        * @defgroup message_hooks Message hooks
        * All message-level hooks look like hook_privatemsg_message_op,
        * where op is one of the following:
        * - @link hook_privatemsg_message_load load @endlink: Called when a full
        *   message is loaded similiar to nodeapi_load, new values can be returned and
        *   will be added to $message, parameter: $message
        * - @link hook_privatemsg_message_validate validate @endlink: Validation,
        *   before the message is sent/saved. Return validation errors as array,
        *   parameter: $message, $form = FALSE
        * - @link hook_privatemsg_message_presave_alter presave_alter @endlink: Last
        *   changes to $message before the message is saved, parameter: $message
        * - @link hook_privatemsg_message_insert insert @endlink: message has been
        *   saved, $message has been updated with the mid and thread_id,
        *   parameter: $message
        * - @link hook_privatemsg_message_delete delete @endlink: the message is
        *   going to be deleted, parameter: $message
        * - @link hook_privatemsg_message_view_alter view_alter @endlink: the message
        *   is going to be displayed, parameter: $vars
        * - @link hook_privatemsg_message_recipient_change recipient changed @endlink:
        *   a recipient is added or removed from/to a message.
+       *
        * In hooks with _alter suffix, $message is by reference.
+       *
        * $message is an array, with all the relevant information about the message.
        * The information in there can be changed/extended by modules, but looks
        * typically like this:
        * @code
        * array (
        *   'mid' => 3517, // message id, identifies a message
        *   'author' => 27, // author id
        *   'subject' => 'raclebugav', // Message subject
        *   'body' => 'bla bla', // Body of the message
        *   'timestamp' => 351287003, // unix timestamp, creation time
        *   'is_new' => 0, // If the message has been read by the user
        *   'thread_id' => 3341, // thread id, this is actually the mid from the first
        *                           message of the thread
        * )
        * @endcode
        */
       /**
        * @addtogroup message_hooks
        * @{
        */
       /**
        * Is called when a message is flushed.
+       *
        * The message will be deleted from the database, remove any related data here.
+       *
        * @param $message
        *   Message array
        */
       function hook_privatemsg_message_flush($message) {
+      }
       /**
        * Validate a message before it is sent/saved in the database.
+       *
        * Validation errors can be returned, either as a string or as array when there
        * are multiple errors. If the $form flag is set, errors should be reported
        * with form_set_error instead.
+       *
        * @todo adapt api return value changes
+       *
        * @param $message
        *   Message array
        */
       function hook_privatemsg_message_validate($message, $form = FALSE) {
         global $_privatemsg_invalid_recipients;
         $_privatemsg_invalid_recipients = array();
         $errors = array();
         foreach ($message->recipients as $recipient) {
           if ($recipient->name == 'blocked user') {
             $_privatemsg_invalid_recipients[] = $recipient->uid;
             $errors[] = t('%name has chosen to not recieve any more messages from you.', array('%name' => privatemsg_recipient_format($recipient, array('plain' => TRUE))));
+          }
+        }
+      }
       /**
        * Change the message before it is stored.
+       *
        * Alter the message, for example remove recipients that have been detected as
        * invalid or forbidden in the validate hook.
+       *
        * @param $message
        *   Message array
        */
       function hook_privatemsg_message_presave_alter(&$message) {
         // delete recipients which have been marked as invalid
         global $_privatemsg_invalid_recipients;
         foreach ($_privatemsg_invalid_recipients as $invalid) {
           unset($message->recipients[$invalid]);
+        }
+      }
       /**
        * Act on the $vars before a message is displayed.
+       *
        * This is called in the preprocess hook of the privatemsg-view template.
        * The $message data is available in $vars['message'].
+       *
        * @param $var
        *   Template variables
        */
       function hook_privatemsg_message_view_alter(&$vars) {
         // add a link to each message
         $vars['message_links'][] = array('title' => t('My link'), 'href' => '/path/to/my/action/' . $vars['message']['mid']);
+      }
       /**
        * This hook is executed after the message has been saved.
+       *
        * $message is updated with mid and thread id. Use this hook to store data,
        * that needs to point to the saved message for example attachments.
+       *
        * @param $message
        *   Message array
        */
       function hook_privatemsg_message_insert($message) {
         _mymodule_save_data($message->mid);
+      }
       /**
        * This hook is invoked when a recipient is added to a message.
+       *
        * Since the hook might be invoked hundreds of times during batch or cron, only
        * ids are passed and not complete user/message objects.
+       *
        * @param $mid
        *   Id of the message.
        * @param $thread_id
        *   Id of the thread the message belongs to.
        * @param $recipient
        *   Recipient id, a user id if type is user or hidden.
        * @param $type
        *   Type of the recipient.
        * @param $added
        *   TRUE if the recipient is added, FALSE if he is removed.
        */
       function hook_privatemsg_message_recipient_changed($mid, $thread_id, $recipient, $type, $added) {
         if ($added && ($type == 'user' || $type == 'hidden')) {
           privatemsg_filter_add_tags(array($thread_id), variable_get('privatemsg_filter_inbox_tag', ''), (object)array('uid' => $recipient));
+        }
+      }
       /**
        * @}
        */
       /**
        * @defgroup generic_hooks Generic Hooks
        * @{
+       *
        * Some generic hooks that can't be categorized.
        */
       /**
        * Check if the author can send a message to the recipients.
+       *
        * This can be used to limit who can write whom based on other modules and/or
        * settings.
+       *
        * @param $author
        *   Author of the message to be sent
        * @param $recipients
        *   Recipient of the message
        * @param $context
        *   Additional information. Can contain the thread_id to indicate that this is
        *   a reply on an existing thread.
        * @return
        *   An indexed array of arrays with the keys recipient ({type}_{key}) and
        *   message (The reason why the recipient has been blocked).
        */
       function hook_privatemsg_block_message($author, $recipients, $context = array()) {
         $blocked = array();
         foreach ($recipients as $recipient_id => $recipient) {
           // Deny/block if the recipient type is role and the account does not have
           // the necessary permission.
           if ($recipient->type == 'role' && $recipient->recipient == 2) {
             $blocked[] = array(
               'recipient' => $recipient_id,
               'message' => t('Not allowed to write private messages to the role authenticated user'),
             );
+          }
+        }
         return $blocked;
+      }
       /**
        * Add content to the view thread page.
+       *
        * @param $content
        *   Render-able array, contains the thread object in #thread.
        */
       function hook_privatemsg_view_alter($content) {
         if (privatemsg_user_access('tag private messages')) {
           $content['tags'] = privatemsg_filter_show_tags($content['#thread']['thread_id'], !empty($_GET['show_tags_form']));
+        }
+      }
       /**
        * List of possible templates.
        */
       function hook_privatemsg_view_template() {
+      }
       /**
        * Expose operations/actions which can be executed on threads.
+       *
        * Return an array of operations to privatemsg, the key of each operation is the
        * operation key or name.
+       *
        * @see _privatemsg_action_form()
        * @see privatemsg_list_submit()
        */
       function hook_privatemsg_thread_operations() {
         return array(
           'operation key' => array(
             'label' => 'Label of the operation. Only use this if the operation
                         should be displayed automatically in the action form',
             'callback' => 'privatemsg_thread_change_status', // Function callback that will be executed.
             'callback arguments' => array('status' => PRIVATEMSG_READ), // Additional arguments to above function
             'undo callback' => 'privatemsg_thread_change_status',  // Provide a function which can "undo" the operation. Optional.
             'undo callback arguments' => array('status' => PRIVATEMSG_UNREAD), // Additional arguments to above function.
           ),
         );
+      }
       /**
        * Allows response to a status change.
+       *
        * @param $pmid
        *   Message id.
        * @param $status
        *   Either PRIVATEMSG_READ or PRIVATEMSG_UNREAD.
        * @param $account
        *   User object, defaults to the current user.
+       *
        * @see privatemsg_message_change_status()
        */
       function hook_privatemsg_message_status_changed($pmid, $status, $account) {
+      }
       /**
        * @}
        */
       /**
        * @defgroup types Types of recipients
+       *
        * It is possible to define other types of recipients than the usual single
        * user. These types are defined through a hook and a few callbacks and are
        * stored in the {pm_index} table for each recipient entry.
+       *
        * Because of that, only the combination of type and recipient (was uid in older
        * versions) defines a unique recipient.
+       *
        * This feature is usually used to define groups of recipients. Privatemsg
        * comes with the privatemsg_roles sub-module, which allows to send messages to
        * all members of a specific group.
+       *
        * When sending a new message with a recipient type other than user, Privatemsg
        * only inserts a single entry for that recipient type. However, when looking
        * for messages for a user, Privatemsg only looks for recipient types user and
        * hidden. To fill the gap, Privatemsg defines three ways how a non-user
        * type is converted to hidden recipient entries.
+       *
        * - For small recipient types (by default <100 recipients, configurable), the
        *   entries are added directly after saving the original private message.
        * - When sending messages through the UI, bigger recipient types are handled
        *   with batch API.
        * - For messages sent by the API, the hidden recipients are generated during
        *   cron runs.
+       *
        * Once all hidden recipients are added, the original recipient type is marked
        * as read so Privatemsg knows that he has been processed.
+       *
        * Privatemsg defines the following types:
+       *
        * - user: This is the default recipient type which is used for a single user.
        * - hidden: Used to add internal recipient entries for other recipient types.
        * - role: The sub-module privatemsg_roles defines an additional type called
        *   role. This allows to send messages to all members of a role.
+       *
        * To implement a new type, the following hooks need to be implemented. Note
        * that most of these hooks can also be used alone for other functionality than
        * defining recipient types.
+       *
        * - hook_privatemsg_recipient_type_info() - Tell Privatemsg about your
        *   recipient type(s).
        * - hook_privatemsg_name_lookup() - Convert a string to an
        *   recipient object
+       *
        * Additionally, there is also a hook_privatemsg_recipient_type_info_alter() that
        * allows to alter recipient type definitions.
        */
       /**
        * @addtogroup types
        * @{
        */
       /**
        * This hook is used to tell privatemsg about the recipient types defined by a
        * module. Each type consists of an array keyed by the internal recipient type
        * name and the following keys must be defined.
+       *
        * * name: Translated name of the recipient type.
        * * description: A short description of how to send messages to to that
        *   recipient type. This is displayed below the To: field when sending a
        *   message.
        * * load: A callback function that can load recipients based on their id,
        *   example: privatemsg_roles_load_multiple().
        * * format: Theme function to format the recipient before displaying. Must be
        *   defined with hook_theme(), example: theme_privatemsg_roles_format().
        * * autocomplete: Function callback to return possible autocomplete matches,
        *   example: privatemsg_roles_autocomplete().
        * * generate recipients: Function callback to return user ids which belong to a
        *   recipient type, example: privatemsg_roles_load_recipients().
        * * max: Function callback to return the highest user id of a recipient type,
        *   example: privatemsg_roles_count_recipients().
        * * write access: Optionally define a permission which controls write access
        *   to that recipient type.
        * * write callback: Optionally define a callback function that returns an
        *   access decision (allow = TRUE, deny = FALSE) for whether the current user
        *   can write to recipients of the given recipient type.
        * * view access: Optionally define a permission which controls if the user is
        *   able to see the recipient when he is looking at a thread.
        * * view callback: Optionally define a callback function that returns an
        *   access decision (allow = TRUE, deny = FALSE) for whether the current user
        *   can see recipients of the given recipient type.
        */
       function hook_privatemsg_recipient_type_info() {
         return array(
           'role' => array(
             'name' => t('Role'),
             'description' => t('Enter the name of a role to write a message to all users which have that role. Example: authenticated user.'),
             'load' => 'privatemsg_roles_load_multiple',
             'format' => 'privatemsg_roles_format',
             'autocomplete' => 'privatemsg_roles_autocomplete',
             'generate recipients' => 'privatemsg_roles_load_recipients',
             'count' => 'privatemsg_roles_count_recipients',
             'write callback' => 'privatemsg_roles_write_access',
             'view access' => 'view roles recipients',
           ),
         );
+      }
       /**
        * Hook which allows to look up a user object.
+       *
        * You can try to look up a user object based on the information passed to the
        * hook. The first hook that successfully looks up a specific string wins.
+       *
        * Therefore, it is important to only return something if you can actually look
        * up the string.
        */
       function hook_privatemsg_name_lookup($string) {
         $result = db_query("SELECT *, rid AS recipient FROM {role} WHERE name = '%s'", trim($string));
         if ($role = db_fetch_object($result)) {
           $role->type = 'role';
           return $role;
+        }
+      }
       /**
        * Allows to alter the defined recipient types.
+       *
        * @param $types
        *   Array with the recipient types.
+       *
        * @see hook_privatemsg_recipient_type_info()
        */
       function hook_privatemsg_recipient_type_info_alter(&$types) {
+      }
       /**
        * Allows to alter the found autocomplete suggestions.
+       *
        * @param $matches
        *   Array of matching recipient objects.
        * @param $names
        *   Array of names that are already in the list.
        * @param $fragment
        *   Fragment that is currently searched for.
        */
       function hook_privatemsg_autocomplete_alter(&$matches, $names, $fragment) {
         // Remove all types other than user if accessed through
         // messages/user/autocomplete.
         if (arg(1) == 'user') {
           foreach ($matches as $id => $match) {
             if ($match->type != 'user') {
               unset($matches[$id]);
+            }
+          }
+        }
+      }
       /**
        * Allows to alter found recipient types for a given string.
+       *
        * @param $matches
        *   Array of matching recipient objects.
        * @param $string
        *   String representation of the recipient.
        */
       function hook_privatemsg_name_lookup_matches(&$matches, $string) {
+      }
       /**
        * Allows response to a successful operation.
+       *
        * @param $operation
        *   The operation that was executed.
        * @param $threads
        *   An array which contains the thread ids on which the operation
        *   has been executed.
        * @param $account
        *   An user account object if an other user than the currently logged in is
        *   affected.
+       *
        * @see privatemsg_operation_execute()
        * @see hook_privatemsg_thread_operations()
        */
       function hook_privatemsg_operation_executed($operation, $threads, $account = NULL) {
+      }
       /**
        * @}
        */

Projet

Général

Profil

Club Drupal

root / drupal7 / sites / all / modules / privatemsg / privatemsg.api.php @ 87dbc3bf