You are here

Home » API reference » Privatemsg 7 » privatemsg.api.php

Types of recipients in Privatemsg 7

Same name and namespace in other branches
  1. 6.2 privatemsg.api.php \types
  2. 7.2 privatemsg.api.php \types

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.

Additionally, there is also a hook_privatemsg_recipient_type_info_alter() that allows to alter recipient type definitions.

File

./privatemsg.api.php, line 399
Privatemsg API Documentation

Functions

Namesort descending Location Description
hook_privatemsg_autocomplete_alter ./privatemsg.api.php Allows to alter the found autocomplete suggestions.
hook_privatemsg_name_lookup ./privatemsg.api.php Hook which allows to look up a user object.
hook_privatemsg_name_lookup_matches ./privatemsg.api.php Allows to alter found recipient types for a given string.
hook_privatemsg_operation_executed ./privatemsg.api.php Allows response to a successful operation.
hook_privatemsg_recipient_type_info ./privatemsg.api.php 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 ./privatemsg.api.php Allows to alter the defined recipient types.
privatemsg_recipient_access ./privatemsg.module This function is used to test if the current user has write/view access for a specific recipient type.
privatemsg_recipient_get_type ./privatemsg.module Return a single recipient type information.
privatemsg_recipient_get_types ./privatemsg.module Returns an array of defined recipient types.
privatemsg_recipient_key ./privatemsg.module Return key for a recipient object used for arrays.