privatemsg.api.php

  1. 1 privatemsg.api.php
  2. 7-1 privatemsg.api.php
  3. 7-2 privatemsg.api.php
  4. 6-2 privatemsg.api.php

Privatemsg API Documentation

File

privatemsg.api.php
View source
  1. <?php
  2. /**
  3. * @file
  4. * Privatemsg API Documentation
  5. */
  6. /**
  7. * @mainpage Privatemsg API Documentation
  8. * This is the (currently inofficial) API documentation of the privatemsg 6.x
  9. * API.
  10. *
  11. * - Topics:
  12. * - @link api API functions @endlink
  13. * - @link sql Query builder and related hooks @endlink
  14. * - @link message_hooks Message hooks @endlink
  15. * - @link generic_hooks Generic hooks @endlink
  16. * - @link theming Theming @endlink
  17. */
  18. /**
  19. * @defgroup sql Query Builder
  20. * Privatemsg does use its own simple query builder which allows to extend
  21. * SELECT-Queries in an easy way. The function _privatemsg_assemble_query
  22. * creates the query, based on an array $fragments with the following content.
  23. * Except primary_table, each key is an array itself to allow multiple values
  24. *
  25. * - primary_table: The main table to select from
  26. * - select: The fields that should be selected. This can be a simple field, a
  27. * field with alias or even a subquery.
  28. * - inner_join: The tables that should be joined. This is not specific to
  29. * inner joins.
  30. * Example: INNER JOIN pm_index pmi ON (pmi.mid = pm.mid)
  31. * - where: The where conditions. The conditions are always AND, but it is
  32. * possible to use OR inside a condition.
  33. * Example: ⁽pmi.is_new = 1 OR pmi.deleted = 1)
  34. * - order_by: Order By values, example: pm.timestamp ASC
  35. * - query_args: It is possible to use the placeholders like %s in each part of
  36. * the query. The values of query_args are then inserted into these.
  37. * query_args consists of three arrays (join, where, having), one for each
  38. * key that currently supports arguments.
  39. *
  40. * Use _privatemsg_assemble_query
  41. *
  42. * The privatemsg_assemble_query function takes a query_id as first argument
  43. * and optionally one or multiple arguments. query_id can either be a
  44. * string ('some_id') or an array('group_name', 'query_id'), if a string
  45. * is supplied, group_name defaults to 'privatemsg'. Returned is an array
  46. * with the keys 'query' (normal query) and 'count' (count query for pager).
  47. *
  48. * For the actual query data, the function group_name_sql_query_id is executed,
  49. * this functions does have $fragments as first parameter and then the
  50. * optional parameters.
  51. *
  52. * A short example:
  53. * @code
  54. * // First, create the sql function.
  55. * function privatemsg_sql_getsubject(&$fragments, $mid, $uid) {
  56. * // Set the primary table.
  57. * $fragments['primary_table'] = '{pm_message} pm';
  58. *
  59. * // Add a field.
  60. * $fragments['select'][] = 'pm.subject';
  61. *
  62. * // Join another table.
  63. * $fragment['inner_join'][] = 'JOIN {pm_index} pi ON (pi.mid = pm.mid)';
  64. * $fragment['query_args']['join'][] $uid;
  65. *
  66. * // And finally add a condition.
  67. * $fragments['where'][] = 'pm.mid = %d';
  68. * $fragments['query_args']['where'][] = $mid;
  69. * }
  70. *
  71. * // Now we can use that query everywhere.
  72. * $query = _privatemsg_assemble_query('getsubject', 5);
  73. * $result = db_query($query['query']);
  74. * @endcode
  75. * Extend existing queries
  76. *
  77. * To extend a privatemsg query, use hook_group_name_sql_query_id_alter.
  78. * This hook does use the same parameters as the sql function.
  79. *
  80. * Example:
  81. * @code
  82. * function mymodule_privatemsg_sql_getsubject_alter(&$fragments, $mid) {
  83. * // we want to load the body too..
  84. * $fragments['select'][] = 'pm.body';
  85. * }
  86. * @endcode
  87. *
  88. * - List of sql query hooks.
  89. * - list: List of messages, Parameters: $fragments, $accounty
  90. * - list_sent: List of sent messages, Parameters: $fragments, $accounty
  91. * - load: Load a single message, Parameters: $fragments, $pmid, $account
  92. * - messages: Load the messages of a thread,
  93. * Parameters: $fragments, $thread_id, $account
  94. * - autocomplete: Searching usernames for the autocomplete feature,
  95. * Parameters: $fragments, $search, $names
  96. * - participants: Loads all participants of a thread,
  97. * Parameters: $fragments, $thread_id
  98. * - unread_count: Number of unread messages for a user,
  99. * Parameters: $fragments, $account
  100. *
  101. * - The following query_id's are used in pm_block_user
  102. * - threadautors: Return all authors of one or multiple threads,
  103. * Parameters: $fragments, $threads
  104. */
  105. /**
  106. * @addtogroup sql
  107. * @{
  108. */
  109. /**
  110. * Query to search for autocomplete usernames.
  111. *
  112. * @param $fragments
  113. * Query fragments
  114. * @param $search
  115. * Search for that username
  116. * @param $names
  117. * Names that are already in the list and are excluded
  118. */
  119. function hook_privatemsg_sql_autocomplete_alter(&$fragments, $search, $names) {
  120. global $user;
  121. // Extend the query that searches for usernames
  122. // $fragments is explained in the api documentation in detail
  123. // The query is already set up, it's searching for usernames which start with
  124. // $search and are not $names (may be empty)
  125. // the main table is {user} a
  126. // for example, add a join on a table where the user connections are stored
  127. // and specify that only users connected with the current user should be
  128. // loaded.
  129. $fragments['inner_join'] = 'INNER JOIN {my_table} m ON (m.user1 = u.uid AND m.user2 = %d)';
  130. $fragments['query_args'][] = $user->uid;
  131. }
  132. /**
  133. * Display a list of threads.
  134. *
  135. * @param $fragments
  136. * Query fragments
  137. * @param $account
  138. * User object
  139. */
  140. function hook_privatemsg_sql_list_alter(&$fragment, $account) {
  141. }
  142. /**
  143. * Query definition to load a message.
  144. *
  145. * @param $fragments
  146. * Query fragments array.
  147. * @param $pmid
  148. * the id of the message.
  149. * @param $account
  150. * User object of account for which to load the message.
  151. */
  152. function hook_privatemsg_sql_load_alter(&$fragments, $pmid, $account = NULL) {
  153. }
  154. /**
  155. * Query definition to load messages of one or multiple threads.
  156. *
  157. * @param $fragments
  158. * Query fragments array.
  159. * @param $threads
  160. * Array with one or multiple thread id's.
  161. * @param $account
  162. * User object for which the messages are being loaded.
  163. * @param $load_all
  164. * Deleted messages are only loaded if this is set to TRUE.
  165. */
  166. function hook_privatemsg_sql_messages_alter(&$fragments, $threads, $account = NULL, $load_all = FALSE) {
  167. }
  168. /**
  169. * Load the participants of a thread.
  170. *
  171. * @param $fragments
  172. * Query fragments
  173. * @param $thread_id
  174. * Thread id, pmi.thread_id is the same as the mid of the first
  175. * message of that thread
  176. */
  177. function hook_privatemsg_sql_participants_alter(&$fragment, $thread_id) {
  178. }
  179. /**
  180. * Loads all unread messages of a user (only the count query is used).
  181. *
  182. * @param $fragments
  183. * Query fragments
  184. * @param $account
  185. * User object
  186. */
  187. function hook_privatemsg_sql_unread_count_alter(&$fragment, $account) {
  188. }
  189. /**
  190. * @}
  191. */
  192. /**
  193. * @defgroup api API functions
  194. *
  195. * There are two different functions to send messages.
  196. * Either by starting a @link privatemsg_new_thread new thread @endlink
  197. * or @link privatemsg_reply reply @endlink to an existing thread.
  198. *
  199. * There is also a function which returns a link to the privatemsg new message
  200. * form with the recipient pre-filled if the user is allowed to.
  201. * privatemsg_get_link().
  202. */
  203. /**
  204. * @defgroup message_hooks Message hooks
  205. * All message-level hooks look like hook_privatemsg_message_op,
  206. * where op is one of the following:
  207. * - @link hook_privatemsg_message_load load @endlink: Called when a full
  208. * message is loaded similiar to nodeapi_load, new values can be returned and
  209. * will be added to $message, parameter: $message
  210. * - @link hook_privatemsg_message_validate validate @endlink: Validation,
  211. * before the message is sent/saved. Return validation errors as array,
  212. * parameter: $message, $form = FALSE
  213. * - @link hook_privatemsg_message_presave_alter presave_alter @endlink: Last
  214. * changes to $message before the message is saved, parameter: $message
  215. * - @link hook_privatemsg_message_insert insert @endlink: message has been
  216. * saved, $message has been updated with the mid and thread_id,
  217. * parameter: $message
  218. * - @link hook_privatemsg_message_delete delete @endlink: the message is
  219. * going to be deleted, parameter: $message
  220. * - @link hook_privatemsg_message_view_alter view_alter @endlink: the message
  221. * is going to be displayed, parameter: $vars
  222. *
  223. * In hooks with _alter suffix, $message is by reference.
  224. *
  225. * $message is an array, with all the relevant information about the message.
  226. * The information in there can be changed/extended by modules, but looks
  227. * typically like this:
  228. * @code
  229. * array (
  230. * 'mid' => 3517, // message id, identifies a message
  231. * 'author' => 27, // author id
  232. * 'subject' => 'raclebugav', // Message subject
  233. * 'body' => 'bla bla', // Body of the message
  234. * 'timestamp' => 351287003, // unix timestamp, creation time
  235. * 'is_new' => 0, // If the message has been read by the user
  236. * 'thread_id' => 3341, // thread id, this is actually the mid from the first
  237. * message of the thread
  238. * )
  239. * @endcode
  240. */
  241. /**
  242. * @addtogroup message_hooks
  243. * @{
  244. */
  245. /**
  246. * Is called after the message has been loaded.
  247. *
  248. * Return data will be merged with the $message array.
  249. *
  250. * @param $message
  251. * Message array
  252. */
  253. function hook_privatemsg_message_load($message) {
  254. return array('my_key' => 'my_value');
  255. }
  256. /**
  257. * Is called when a message is flushed.
  258. *
  259. * The message will be deleted from the database, remove any related data here.
  260. *
  261. * @param $message
  262. * Message array
  263. */
  264. function hook_privatemsg_message_flush($message) {
  265. }
  266. /**
  267. * Validate a message before it is sent/saved in the database.
  268. *
  269. * Validation errors can be returned, either as a string or as array when there
  270. * are multiple errors. If the $form flag is set, errors should be reported
  271. * with form_set_error instead.
  272. *
  273. * @todo adapt api return value changes
  274. *
  275. * @param $message
  276. * Message array
  277. */
  278. function hook_privatemsg_message_validate($message, $form = FALSE) {
  279. global $_privatemsg_invalid_recipients;
  280. $_privatemsg_invalid_recipients = array();
  281. $errors = array();
  282. foreach ($message['recipients'] as $recipient) {
  283. if ($recipient->name == 'blocked user') {
  284. $_privatemsg_invalid_recipients[] = $recipient->uid;
  285. $errors[] = t('%name has chosen to not recieve any more messages from you.', array('%name' => $recipient->name));
  286. }
  287. }
  288. }
  289. /**
  290. * Change the message before it is stored.
  291. *
  292. * Alter the message, for example remove recipients that have been detected as
  293. * invalid or forbidden in the validate hook.
  294. *
  295. * @param $message
  296. * Message array
  297. */
  298. function hook_privatemsg_message_presave_alter(&$message) {
  299. // delete recipients which have been marked as invalid
  300. global $_privatemsg_invalid_recipients;
  301. foreach ($_privatemsg_invalid_recipients as $invalid) {
  302. unset($message['recipients'][$invalid]);
  303. }
  304. }
  305. /**
  306. * Act on the $vars before a message is displayed.
  307. *
  308. * This is called in the preprocess hook of the privatemsg-view template.
  309. * The $message data is aviable in $vars['message'].
  310. *
  311. * @param $var
  312. * Template variables
  313. */
  314. function hook_privatemsg_message_view_alter(&$var) {
  315. // add a link to each message
  316. $vars['message_links'][] = array('title' => t('My link'), 'href' => '/path/to/my/action/'. $vars['message']['mid']);
  317. }
  318. /**
  319. * This hook is executed after the message has been saved.
  320. *
  321. * $message is updated with mid and thread id. Use this hook to store data,
  322. * that needs to point to the saved message for example attachments.
  323. *
  324. * @param $message
  325. * Message array
  326. */
  327. function hook_privatemsg_message_insert($message) {
  328. _mymodule_save_data($message['mid']);
  329. }
  330. /**
  331. * @}
  332. */
  333. /**
  334. * @defgroup generic_hooks Generic Hooks
  335. * @{
  336. *
  337. * Some generic hooks that can't be categorized.
  338. */
  339. /**
  340. * Check if the author can send a message to the recipients.
  341. *
  342. * This can be used to limit who can write whom based on other modules and/or
  343. * settings.
  344. *
  345. * @param $author
  346. * Author of the message to be sent
  347. * @param $recipients
  348. * Recipients of the message
  349. * @return
  350. * An indexed array of arrays with the keys uid and
  351. * message (The reason why the recipient has been blocked).
  352. */
  353. function hook_privatemsg_block_message($author, $recipients) {
  354. $blocked = array();
  355. // Loop through each recipient and ensure there is no rule blocking this
  356. // author from sending them private messages. Use a reference, so when
  357. // user_load() is needed here the array is updated, negating the need for
  358. // further calls to user_load() later in the code.
  359. foreach (array_keys($recipients) as $uid) {
  360. // Ensure we have a recipient user object which includes roles.
  361. if (!isset($recipients[$uid]->roles)) {
  362. $recipients[$uid] = user_load($uid);
  363. }
  364. // Note: this is checked whether the author may send the message (see third
  365. // parameter). Further below is a check whether the recipient may block it.
  366. if (_pm_block_user_rule_exists($author, $recipients[$uid], PM_BLOCK_USER_DISALLOW_SENDING)) {
  367. $blocked[] = array(
  368. 'uid' => $uid,
  369. 'message' => t('Sorry, private messaging rules forbid sending messages to !name.', array('!name' => $recipients[$uid]->name)),
  370. );
  371. }
  372. }
  373. $args = array_merge(array($author->uid), array_keys($recipients));
  374. $result = db_query('SELECT recipient FROM {pm_block_user} WHERE author = %d AND recipient IN ('. db_placeholders($recipients) .') GROUP BY recipient', $args);
  375. while ($row = db_fetch_array($result)) {
  376. $recipient = $recipients[$row['recipient']];
  377. // If there's a rule disallowing blocking of this message, send it anyway.
  378. if (_pm_block_user_rule_exists($author, $recipient, PM_BLOCK_USER_DISALLOW_BLOCKING)) {
  379. continue;
  380. }
  381. $blocked[] = array(
  382. 'uid' => $row['recipient'],
  383. 'message' => t('%name has chosen to not recieve any more messages from you.', array('%name' => $recipients[$row['recipient']]->name))
  384. );
  385. }
  386. return $blocked;
  387. }
  388. /**
  389. * Add content to the view thread page.
  390. *
  391. * Each element in content contains a 'value' and a '#weight' key, the weight
  392. * is used set the order of the different parts.
  393. *
  394. * @param $content
  395. * Content array
  396. * @param $message_count
  397. * Amount of messages
  398. */
  399. function hook_privatemsg_view_messages($content, $message_count) {
  400. }
  401. /**
  402. * List of possible templates.
  403. */
  404. function hook_privatemsg_view_template() {
  405. }
  406. /**
  407. * Expose operations/actions which can be executed on threads.
  408. *
  409. * Return an array of operations to privatemsg, the key of each operation is the
  410. * operation key or name.
  411. *
  412. * @see _privatemsg_action_form()
  413. * @see privatemsg_list_submit()
  414. */
  415. function hook_privatemsg_thread_operations() {
  416. return array(
  417. 'operation key' => array(
  418. 'label' => 'Label of the operation. Only use this if the operation
  419. should be displayed automatically in the action form',
  420. 'callback' => 'privatemsg_thread_change_status', // Function callback that will be executed.
  421. 'callback arguments' => array('status' => PRIVATEMSG_READ), // Additional arguments to above function
  422. 'undo callback' => 'privatemsg_thread_change_status', // Provide a function which can "undo" the operation. Optional.
  423. 'undo callback arguments' => array('status' => PRIVATEMSG_UNREAD), // Additional arguments to above function.
  424. ),
  425. );
  426. }
  427. /**
  428. * Hook which allows to look up a user object.
  429. *
  430. * You can try to look up a user object based on the information passed to the
  431. * hook. The first hook that successfully looks up a specific string wins.
  432. *
  433. * Therefore, it is important to only return something if you can actually look
  434. * up the string.
  435. */
  436. function hook_privatemsg_name_lookup($string) {
  437. if ((int)$string > 0) {
  438. // This is a possible uid, try to load a matching user.
  439. if ($recipient = user_load(array('uid' => $string))) {
  440. return $recipient;
  441. }
  442. }
  443. }
  444. /**
  445. * @}
  446. */

Functions

Namesort descending Description
hook_privatemsg_block_message Check if the author can send a message to the recipients.
hook_privatemsg_message_flush Is called when a message is flushed.
hook_privatemsg_message_insert This hook is executed after the message has been saved.
hook_privatemsg_message_load Is called after the message has been loaded.
hook_privatemsg_message_presave_alter Change the message before it is stored.
hook_privatemsg_message_validate Validate a message before it is sent/saved in the database.
hook_privatemsg_message_view_alter Act on the $vars before a message is displayed.
hook_privatemsg_name_lookup Hook which allows to look up a user object.
hook_privatemsg_sql_autocomplete_alter Query to search for autocomplete usernames.
hook_privatemsg_sql_list_alter Display a list of threads.
hook_privatemsg_sql_load_alter Query definition to load a message.
hook_privatemsg_sql_messages_alter Query definition to load messages of one or multiple threads.
hook_privatemsg_sql_participants_alter Load the participants of a thread.
hook_privatemsg_sql_unread_count_alter Loads all unread messages of a user (only the count query is used).
hook_privatemsg_thread_operations Expose operations/actions which can be executed on threads.
hook_privatemsg_view_messages Add content to the view thread page.
hook_privatemsg_view_template List of possible templates.