function privatemsg_new_thread

1 privatemsg.module privatemsg_new_thread($recipients, $subject, $body = NULL, $options = array())
7-1 privatemsg.module privatemsg_new_thread($recipients, $subject, $body = NULL, $options = array())
7-2 privatemsg.module privatemsg_new_thread($recipients, $subject, $body = NULL, $options = array())
6-2 privatemsg.module privatemsg_new_thread($recipients, $subject, $body = NULL, $options = array())

Send a new message.

This functions does send a message in a new thread. Example:

privatemsg_new_thread(array(user_load(5)), 'The subject', 'The body text');

Parameters

$recipients: Array of recipients (user objects)

$subject: The subject of the new message

$body: The body text of the new message

$options: Additional options, possible keys: author => User object of the author timestamp => Time when the message was sent

Return value

An array with a key success. If TRUE, it also contains a key 'message' with the created $message array, the same that is passed to the insert hook. If FALSE, it contains a key 'messages'. This key contains an array where the key is the error type (error, warning, notice) and an array with messages of that type.

It is theoretically possible for success to be TRUE and message to be FALSE. For example if one of the privatemsg database tables become corrupted. When testing for success of message being sent it is always best to see if ['message'] is not FALSE as well as ['success'] is TRUE.

Example:

  array('error' => array('A error message'))
  

Related topics

File

./privatemsg.module, line 1653
Allows users to send private messages to other users.

Code

function privatemsg_new_thread($recipients, $subject, $body = NULL, $options = array()) {
  global $user;
  $author = clone $user;

  $message = (object) $options;
  $message->subject = $subject;
  $message->body = $body;
  // Make sure that recipients are keyed correctly and are not added
  // multiple times.
  foreach ($recipients as $recipient) {
    if (!isset($recipient->type)) {
      $recipient->type = 'user';
      $recipient->recipient = $recipient->uid;
    }
    $message->recipients[privatemsg_recipient_key($recipient)] = $recipient;
  }

  // Apply defaults - this will not overwrite existing keys.
  if (!isset($message->author)) {
    $message->author = $author;
  }
  if (!isset($message->timestamp)) {
    $message->timestamp = REQUEST_TIME;
  }
  if (!isset($message->format)) {
    $message->format = filter_default_format($message->author);
  }

  $validated = _privatemsg_validate_message($message);
  if ($validated['success']) {
    $validated['message'] = _privatemsg_send($message);
    if ($validated['message'] !== FALSE) {
      _privatemsg_handle_recipients($validated['message']->mid, $validated['message']->recipients, FALSE);
    }
  }

  return $validated;
}