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.
Functions & methods
| Name | Description |
|---|---|
| hook_privatemsg_autocomplete_alter | Allows to alter the found autocomplete suggestions. |
| hook_privatemsg_name_lookup | Hook which allows to look up a user object. |
| hook_privatemsg_name_lookup_matches | Allows to alter found recipient types for a given string. |
| hook_privatemsg_operation_executed | Allows response to a successful operation. |
| hook_privatemsg_recipient_type_info | 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. |
| hook_privatemsg_recipient_type_info_alter | Allows to alter the defined recipient types. |
| privatemsg_recipient_access | This function is used to test if the current user has write/view access for a specific recipient type. |
| privatemsg_recipient_get_type | Return a single recipient type information. |
| privatemsg_recipient_get_types | Returns an array of defined recipient types. |
| privatemsg_recipient_key | Return key for a recipient object used for arrays. |
File
- ./
privatemsg.api.php, line 399 - Privatemsg API Documentation
Add new comment