Index: privatemsg.module
===================================================================
RCS file: /cvs/drupal/contributions/modules/privatemsg/privatemsg.module,v
retrieving revision 1.70.2.30.2.91.2.43
diff -u -p -r1.70.2.30.2.91.2.43 privatemsg.module
--- privatemsg.module	23 Apr 2009 00:18:36 -0000	1.70.2.30.2.91.2.43
+++ privatemsg.module	23 Apr 2009 21:29:50 -0000
@@ -726,14 +726,17 @@ function pm_send_validate($form, &$form_
   }
 }
 
+/**
+ * Submit callback for the privatemsg_new form.
+ */
 function pm_send($form, &$form_state) {
-  if (_privatemsg_send($form_state['validate_built_message'])) {    // Load usernames to which the message was sent to
-    $recipient_names = array();
-    foreach ($form_state['validate_built_message']['recipients'] as $recipient) {
-      $recipient_names[] = theme('username', $recipient);
-    }
-    drupal_set_message(t('A message has been sent to !recipients.', array('!recipients' => implode(', ', $recipient_names))));
+  _privatemsg_send($form_state['validate_built_message']);
+  // Load usernames to which the message was sent to.
+  $recipient_names = array();
+  foreach ($form_state['validate_built_message']['recipients'] as $recipient) {
+    $recipient_names[] = theme('username', $recipient);
   }
+  drupal_set_message(t('A message has been sent to !recipients.', array('!recipients' => implode(', ', $recipient_names))));
 }
 
 function pm_preview($form, &$form_state) {
@@ -1143,7 +1146,16 @@ function privatemsg_delete_submit($form,
  *     timestamp => Time when the message was sent
  *
  * @return
- *   Either true or an array with validation errors
+ *   An array with a key success and messages. This key contains an array where
+ *   the key is the error type (error, warning, notice) and an array with
+ *   messages of that type.. If success is TRUE, it also contains a key $message
+ *   with the created $message array, the same that is passed to
+ *   hook_privatemsg_message_insert().
+ *
+ *   Example messages values:
+ *   @code
+ *   array('error' => array('A error message'))
+ *   @endcode
  *
  * @ingroup api
  */
@@ -1168,7 +1180,7 @@ function privatemsg_new_thread($recipien
 
   $validated = _privatemsg_validate_message($message);
   if ($validated['success']) {
-    $validated['success'] = _privatemsg_send($message);
+    $validated['message'] = _privatemsg_send($message);
   }
 
   return $validated;
@@ -1188,7 +1200,16 @@ function privatemsg_new_thread($recipien
  *     timestamp => Time when the message was sent
  *
  * @return
- *   Either true or an array with validation errors
+ *   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.
+ *
+ *   Example:
+ *   @code
+ *   array('error' => array('A error message'))
+ *   @endcode
  *
  * @ingroup api
  */
@@ -1228,11 +1249,21 @@ function privatemsg_reply($thread_id, $b
 
   $validated = _privatemsg_validate_message($message);
   if ($validated['success']) {
-    $validated['success'] = _privatemsg_send($message);
+    $validated['message'] = _privatemsg_send($message);
   }
   return $validated;
 }
 
+/**
+ * Validate a $message array.
+ *
+ * @param $message
+ *   A message array containing the message that should be validated.
+ * @param $form
+ *   A flag that indicates if errors should be returned or displayed.
+ * @return
+ *   A array with a key success and a key messages.
+ */
 function _privatemsg_validate_message(&$message, $form = FALSE) {
   $messages = array('error' => array(), 'warning' => array());
   if (!privatemsg_user_access('write privatemsg', $message['author'])) {
@@ -1289,13 +1320,25 @@ function _privatemsg_validate_message(&$
   }
 
   $messages += module_invoke_all('privatemsg_message_validate', $message, $form);
-  $success = empty($messages['error']);
+  // Check if there are errors in $messages or if $form is TRUE, there are form errors.
+  $success = empty($messages['error']) || ($form && count((array)form_get_errors()) > 0);
   return array(
     'success'  => $success,
     'messages'   => $messages,
   );
 }
 
+/**
+ * Internal function to save a message.
+ *
+ * @param $message
+ *   A $message array with the data that should be saved. If a thread_id exists
+ *   it will be created as a reply to an existing thread. If not, a new thread
+ *   will be created.
+ *
+ * @return
+ *   The updated $message array.
+ */
 function _privatemsg_send($message) {
 
   drupal_alter('privatemsg_message_presave', $message);
@@ -1329,7 +1372,7 @@ function _privatemsg_send($message) {
 
   module_invoke_all('privatemsg_message_insert', $message);
 
-  return TRUE;
+  return $message;
 }
 
 /**