vinculum.module

<?php
/**
 * @file
 * Provide an API for vinculum-handlers to support vinculum-registration on
 * nodes.  At least one vinculum-handler (such as Pingback or Trackback) should
 * be enabled.
 */


/**
 * @defgroup vinculum_validation_error_codes Vinculum error codes.
 * @{
 * Numeric error codes used to report errors when recording the receipt of a
 * vinculum.
 * @}
 */

/**
 * @addtogroup vinculum_validation_error_codes
 * @{
 */

// Zero means the vinculum is valid.
define('VINCULUM_VALIDATES', 0);

// The local node could not be found.
define('VINCULUM_ERROR_LOCAL_NODE_NOT_FOUND', 1);

// The local node could not be used as a vinculum resource (e.g. vinculums are
// disabled on the node).
define('VINCULUM_ERROR_LOCAL_NODE_VINCULUM_NOT_ALLOWED', 2);

// The pingback has previously been registered.
define('VINCULUM_ERROR_VINCULUM_ALREADY_REGISTERED', 3);

// The URL of the remote site could not be reached.
define('VINCULUM_ERROR_REMOTE_URL_NOT_FOUND', 4);

// The response from the remote resource does not contain a link to this site.
define('VINCULUM_ERROR_REMOTE_URL_MISSING_LINK', 5);


/**
 * @} End of "addtogroup vinculum_validation_error_codes".
 */

/**********************************************************
 * Hook implementations.
 *********************************************************/

/**
 * Implements hook_help().
 */
function vinculum_help($path, $arg) {
  // Explain:
  // - Vinculum protocol
  // - Trackback protocol
  // Send vs Receive
  // Adding as comments/entities...
  // Moderation (Mollom integration?)

  switch ($path) {
    // Main help for the Vinculum module.
    case 'admin/help#vinculum':
      break;

    // The configuration page.
    case 'admin/config/content/vinculum':
      $output = '';
      $output .= '<p>' . t('The vinculum handlers are prioritised by module-weight.') . '</p>';
      return $output;
  }
}

/**
 * Implements hook_permission().
 */
function vinculum_permission() {
  $perms = array();
  // This permission controls access to the admin-settings page, and
  // automatically grants access to configure vinculum settings on any node-
  // type that the user has permission to edit.
  $perms['configure vinculum settings'] = array(
    'title' => t('Administer vinculum settings'),
  );
  $perms['view vinculum reports'] = array(
    'title' => t('View vinculum reports'),
  );

  foreach (node_permissions_get_configured_types() as $type) {
    $perms += _vinculum_list_permissions($type);
  }
  return $perms;
}

/**
 * Implements hook_theme().
 */
function vinculum_theme() {
  return array(
    'vinculum_settings_handlers_form_element' => array(
      'render element' => 'form',
      'file' => 'vinculum.admin.inc',
    ),
  );
}

/**
 * Implements hook_menu().
 */
function vinculum_menu() {
  // Configuration page.
  $items['admin/config/content/vinculum'] = array(
    'title' => 'Vinculum',
    'description' => 'Configure trackbacks and pingbacks.',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('vinculum_settings_form'),
    'access arguments' => array('configure vinculum settings'),
    'file' => 'vinculum.admin.inc',
  );

  // Reporting.
  $items['admin/reports/vinculum'] = array(
    'title' => 'Vinculum',
    'description' => 'List vinculums sent and received.',
    'page callback' => 'vinculum_report_sent',
    'access arguments' => array('view vinculum reports'),
    'file' => 'vinculum.admin.inc',
  );
  $items['admin/reports/vinculum/sent'] = array(
    'title' => 'Sent',
    'type' => MENU_DEFAULT_LOCAL_TASK,
    'weight' => -10,
  );
  $items['admin/reports/vinculum/received'] = array(
    'title' => 'Received',
    'page callback' => 'vinculum_report_received',
    'access arguments' => array('view vinculum reports'),
    'file' => 'vinculum.admin.inc',
    'type' => MENU_LOCAL_TASK,
  );

  return $items;
}

/**
 * Implements hook_form_FORM_ID_alter().
 *
 * Configure which content-types can send/receive vinculums.
 */
function vinculum_form_node_type_form_alter(&$form, &$form_state) {
  $type = $form['#node_type'];

  // The JS adds an appropriate description to the vertical-tab for Vinculums
  // based on the chosen settings.
  $form['additional_settings']['#attached']['js'][] = drupal_get_path('module', 'vinculum') . '/vinculum_content_types.js';

  $form['vinculum'] = array(
    '#type' => 'fieldset',
    '#title' => t('Vinculums'),
    '#description' => t('Default settings for new content:'),
    '#collapsible' => TRUE,
    '#collapsed' => TRUE,
    '#group' => 'additional_settings',
  );
  $form['vinculum']['vinculum_receive'] = array(
    '#type' => 'checkbox',
    '#title' => t('Receive vinculums'),
    '#description' => t('Allow %type nodes to receive vinculums from third party sites.', array('%type' => $type->name)),
    '#default_value' => variable_get("vinculum_receive_{$type->type}", TRUE),
  );
  $form['vinculum']['vinculum_send'] = array(
    '#type' => 'checkbox',
    '#title' => t('Send vinculums'),
    '#description' => t('Allow %type nodes to send vinculums to third party sites when the node is created or changed.', array('%type' => $type->name)),
    '#default_value' => variable_get("vinculum_send_{$type->type}", TRUE),
  );
}

/**
 * Implements hook_form_alter().
 */
function vinculum_form_alter(&$form, $form_state, $form_id) {

  // Add 'send' and 'receive' controls to node/add and node/nnn/edit forms.
  if (strpos($form_id, '_node_form') && isset($form['#node'])) {
    $node = $form['#node'];
    $node_type = $form['#node']->type;

    // Get the configured vinculum settings for this node (if already set), or
    // the defaults for the node's content-type.
    $settings = (object) array(
      'send'    => isset($node->vinculum_send)    ? $node->vinculum_send    : variable_get("vinculum_send_{$node_type}", TRUE),
      'receive' => isset($node->vinculum_receive) ? $node->vinculum_receive : variable_get("vinculum_receive_{$node_type}", TRUE),
    );

    // Users may control whether vinculums (send / receive) are enabled for a
    // given node if they have permission for that node-type, or a global admin
    // permission.
    $access = user_access("configure {$node_type} vinculums") || user_access('administer content types') || user_access('configure vinculum settings');

    // The JS handles the vertical-tabs text.
    $form['additional_settings']['#attached']['js'][] = drupal_get_path('module', 'vinculum') . '/vinculum_content_types.js';

    $form['vinculum'] = array(
      '#type' => 'fieldset',
      '#title' => t('Vinculums'),
      '#collapsible' => TRUE,
      '#collapsed' => TRUE,
      '#group' => 'additional_settings',
      '#access' => $access,
    );
    $form['vinculum']['vinculum_receive'] = array(
      '#type' => 'checkbox',
      '#title' => t('Receive vinculums'),
      '#default_value' => $settings->receive,
    );
    $form['vinculum']['vinculum_send'] = array(
      '#type' => 'checkbox',
      '#title' => t('Send vinculums'),
      '#default_value' => $settings->send,
    );
  }
}

/**
 * Implements hook_node_load().
 *
 * When a node is loaded, add the 'send' and 'receive' vinculum attributes to
 * the node object.
 */
function vinculum_node_load($nodes, $types) {
  $nids = array_keys($nodes);

  // Load the vinculum settings for these nodes.
  $vinculum_node_settings = _vinculum_node_get_settings($nids);

  foreach ($nids as $nid) {
    // If this node has already been configured, use the node's settings.
    if (array_key_exists($nid, $vinculum_node_settings)) {
      $nodes[$nid]->vinculum_send    = $vinculum_node_settings[$nid]->send;
      $nodes[$nid]->vinculum_receive = $vinculum_node_settings[$nid]->receive;
    }
    // Fallback to defaults.
    else {
      $node_type = $nodes[$nid]->type;
      $nodes[$nid]->vinculum_send    = variable_get("vinculum_send_{$node_type}", TRUE);
      $nodes[$nid]->vinculum_receive = variable_get("vinculum_receive_{$node_type}", TRUE);
    }
  }
}

/**
 * Implements hook_node_insert().
 */
function vinculum_node_insert($node) {
  _vinculum_node_save($node);
}

/**
 * Implements hook_node_update().
 */
function vinculum_node_update($node) {
  _vinculum_node_save($node);
}



/**
 * Implements hook_vinculum_get_external_links().
 * Gets all the URLs found in the body field of a node.
 *
 * @return Array
 * A list of external links found within the BODY field.
 */
function vinculum_vinculum_get_external_links($node) {
  $text = _vinculum_extract_text($node);
  return _vinculum_extract_urls($text);
}

/**
 * Implements hook_vinculum_link_send_alter().
 *
 * Hook function provided on behalf of core's path functionality to support
 * URL aliases for nodes.
 */
function vinculum_vinculum_link_send_alter(&$links, $node) {
  foreach ($links as $key => $record) {
    $language = (isset($node->language)) ? $node->language : LANGUAGE_NONE;
    if ($url = drupal_lookup_path('alias', $record->source, $language)) {
      $links[$key]->source = $url;
    }
  }
}



/**********************************************************
 * Public API functions.
 *********************************************************/

/**
 * Register the receipt of a vinculum.
 *
 * If the vinculum has not been validated, this function will call the
 * validation handlers.
 * This function will trigger vinculum actions (such as add-comment) when a
 * vinculum has been successfully validated.
 *
 * @param Object $vinculum A vinculum object.
 *
 * @return Int
 * 0 is returned if the vinculum was successfully added.
 * A positive numeric error-code is returned if the vinculum was declined (e.g.
 * the vinculum already exists, or an anti-spam module prevented the pingback,
 * etc).
 *
 * @see vinculum_validation_error_codes
 */
function vinculum_receive(vinculum $vinculum) {

  // Validate the vinculum request, if it's not already validated.
  if (empty($vinculum->validated)) {
    $validation_result = vinculum_receive_validate($vinculum);

    // If it's invalid, abort here.
    if (!$validation_result == VINCULUM_VALIDATES) {
      return $validation_result;
    }
  }

  // Write an entry in the vinculum tracker table.
  db_merge('node_vinculum_received')
    ->key(array(
      'nid' => $vinculum->nid,
      'url' => $vinculum->url,
      ))
    ->fields(array(
      'handler'   => $vinculum->handler,
      'origin_ip' => $vinculum->origin_ip,
      'timestamp' => $vinculum->timestamp,
    ))
    ->execute();

  // Fire hook_vinculum_received_action().
  // Actions are implemented through:
  // - vinculum_trigger - supports the core trigger module.
  // - vinculum_rules - integrates with the rules module.
  module_invoke_all('vinculum_received_action', $vinculum);

}


/**
 * Validate the receipt of a vinculum.
 *
 * @param Object $vinculum A vinculum object.
 *
 * @return Int
 * 0 is returned if the vinculum validates.
 * A positive numeric error-code is returned if the vinculum validation fails
 * (e.g. the vinculum already exists, or an anti-spam module prevented the
 * pingback, etc).
 *
 * @see vinculum_validation_error_codes
 */
function vinculum_receive_validate(vinculum $vinculum) {
  // Validate that the node accepts pingbacks.
  $node = node_load($vinculum->nid);
  if (!$node) {
    return VINCULUM_ERROR_LOCAL_NODE_NOT_FOUND;
  }
  // Check that the node permits vinculums.
  elseif (!vinculum_node_allows_vinculum($node, 'receive')) {
    return VINCULUM_ERROR_LOCAL_NODE_VINCULUM_NOT_ALLOWED;
  }
  // Check that the vinculum isn't already registered.
  elseif (vinculum_is_received($vinculum->nid, $vinculum->url)) {
    return VINCULUM_ERROR_VINCULUM_ALREADY_REGISTERED;
  }

  // Optional validation:
  // Validate that the remote URL is reachable and links to the referenced
  // node.
  if (variable_get('vinculum_validate_remote_pages', FALSE)) {
    // Validate that the remote node is reachable.
    $result = drupal_http_request($vinculum->url);

    // Treat all HTTP errors (inc Forbidden) as remote URL not found.
    if ($result->error) {
      return VINCULUM_ERROR_REMOTE_URL_NOT_FOUND;
    }

    // Check the content for a link to the local node.
    $content = $result->data;
    // Extract all the URLs from the page content.
    $urls = _vinculum_extract_urls($content);
    $matched = FALSE;
    foreach ($urls as $url) {
      if ($nid = vinculum_lookup_nid($url)) {
        $matched = TRUE;
        break;
      }
    }
    if (!$matched) {
      return VINCULUM_ERROR_REMOTE_URL_MISSING_LINK;
    }
  }

  // @TODO: Allow other modules to add their own validation routines.

  return VINCULUM_VALIDATES;
}


/**
 * Parse a node and send vinculums to the discovered URLs (which haven't
 * already recorded a successful vinculum).
 * Note that this function does not respect the node's "vinculum_send" property
 * - modules which invoke this function directly should check the node's
 * settings first to ensure the node permits vinculums to be sent.
 *
 * @param Object $node
 * A fully loaded node object (or one which is in the process of being saved).
 */
function vinculum_node_process($node) {
  // Look for external links.
  $links = vinculum_get_external_links($node);
  vinculum_send_vinculums($links, $node);
}

/**
 * Check if a node allows vinculum operations.
 *
 * @param Object $node
 * The node to check.
 * @param String $op
 * One of:
 * - send
 * - receive
 *
 * @return Boolean
 */
function vinculum_node_allows_vinculum($node, $op) {
  // Both send and receive ops depend on the node allowing anonymous access.
  if (!node_access('view', $node, drupal_anonymous_user())) {
    return FALSE;
  }

  switch ($op) {
    case 'send':
      return isset($node->vinculum_send) ? $node->vinculum_send : variable_get("vinculum_send_{$node->type}", TRUE);

    case 'receive':
      return isset($node->vinculum_receive) ? $node->vinculum_receive : variable_get("vinculum_receive_{$node->type}", TRUE);
  }
}

/**
 * Get a list of external links from a node.
 *
 * This invokes hook_vinculum_get_external_links.
 * By default, the vinculum module checks only the BODY field.  Create an
 * implementation of hook_vinculum_get_external_links() to check other fields.
 *
 * @param Object $node
 * The node to check.
 *
 * @return array
 * An array of external link URLs.
 */
function vinculum_get_external_links($node) {
  $links = module_invoke_all('vinculum_get_external_links', $node);

  // Remove duplicate links.
  $links = array_unique($links);

  return $links;
}


/**
 * Invoke vinculum handlers on each external link to record a vinculum.
 *
 * @param Array $links
 * An array of external URLs.
 */
function vinculum_send_vinculums($links, $node) {
  // The initial source URL is defined as node/xxx.  The vinculum module
  // provides an implementation of hook_vinculum_link_send_alter for the path
  // module to support node-aliases.
  $source = "node/{$node->nid}";

  // Build up a list of vinculum records for altering.
  $records = array();
  foreach ($links as $link) {
    $records[$link] = (object) array(
      'source' => $source,
      'target' => $link,
    );
  }

  // Invoke hook_vinculum_link_send_alter().
  // Allow other modules to change the source/target URLs before sending
  // vinculums.
  // The node property is unalterable.
  drupal_alter('vinculum_link_send', $records, $node);

  foreach ($records as $record) {
    if (!vinculum_is_sent($node->nid, $record->target)) {
      vinculum_send_single_vinculum($record->source, $record->target, $node);
    }
  }
}

/**
 * Invoke vinculum handlers to send a vinculum.
 *
 * @param String $source
 * The canonical URL of the local node.
 * @param String $target
 * The URL of the remote page.
 * @param Object $node
 * The local node object.
 *
 * @return Boolean
 * TRUE if the remote server accepts the vinculum request.
 */
function vinculum_send_single_vinculum($source, $target, $node) {
  // Record the timestamp of this attempt in the {node_vinculum_sent} table.
  // This allows vinculums which have not been successful to be re-attempted
  // periodically.
  db_merge('node_vinculum_sent')
    ->key(array(
      'nid' => $node->nid,
      'url' => $target,
      ))
    ->fields(array(
      'timestamp' => time(),
    ))
    ->execute();

  $handlers = vinculum_get_handler();
  foreach ($handlers as $handler) {
    // Invoke hook_vinculum_send().
    $callback = $handler->module . '_vinculum_send';
    // Ensure the function exists before attempting to call it.
    if (!function_exists($callback)) {
      continue;
    }
    $success = $callback($target, $source, $node);

    // If the handler reports success, log this as a successful request.
    if ($success) {
      $params = array(
        '%target'     => $target,
        '@node_url'   => url("node/{$node->nid}"),
        '%node_title' => $node->title,
        '%handler'    => $handler->module,
      );
      watchdog('Vinculum', 'Vinculum sent to %target for node <a href="@node_url">%node_title</a> using %handler.', $params, WATCHDOG_DEBUG);

      db_merge('node_vinculum_sent')
        ->key(array(
          'nid' => $node->nid,
          'url' => $target,
          ))
        ->fields(array(
          'handler' => $handler->module,
        ))
        ->execute();
      // Stop at the first successful handler.
      return TRUE;
    }
  }

  $params = array(
    '%target'     => $target,
    '@node_url'   => url("node/{$node->nid}"),
    '%node_title' => $node->title,
  );
  watchdog('Vinculum', 'Vinculum could not be sent to %target for node <a href="@node_url">%node_title</a> - no vinculum support found.', $params, WATCHDOG_DEBUG);
  return FALSE;
}


/**
 * Fetch the node nid from a local URL.
 *
 * Handles standard drupal paths such as node/1 and drupal aliases.
 *
 * @param String $url
 * The URL of a node on this site.
 *
 * @return Int|FALSE
 * The node nid (if a match for the URL is found), or FALSE.
 */
function vinculum_lookup_nid($url) {
  // Strip the domain from the URL (if present).
  if (preg_match('#^(https?://[^/]+/).*#', $url, $matches)) {
    $url = drupal_substr($url, drupal_strlen($matches[1]));
  }

  // Lookup URL aliases.
  if ($local_path = drupal_lookup_path('source', $url)) {
    $url = $local_path;
  }

  if (preg_match('#^node/(\d+)$#', $url, $matches)) {
    return (int) $matches[1];
  }
  return FALSE;
}

/**
 * Check if a vinculum has already been received for a particular node/URL.
 *
 * @param Int $nid
 * The node nid.
 * @param String $url
 * The URL of the external site.
 *
 * @return Boolean
 * TRUE if the vinculum has already been registered.
 */
function vinculum_is_received($nid, $url) {
  $result = db_select('node_vinculum_received', 'nlr', array('target' => 'slave'))
    ->fields('nlr', array('nid'))
    ->condition("nlr.nid", $nid)
    ->condition("nlr.url", $url)
    ->execute()
    ->fetchField();
  return (bool) $result;
}

/**
 * Check if a vinculum has already been sent for a particular node/URL.
 *
 * @param Int $nid
 * The node nid.
 * @param String $url
 * The URL of the external site.
 *
 * @return Boolean
 * TRUE if the vinculum has already been sent.
 */
function vinculum_is_sent($nid, $url) {
  $result = db_select('node_vinculum_sent', 'nls', array('target' => 'slave'))
    ->fields('nls', array('nid'))
    ->condition("nls.nid", $nid)
    ->condition("nls.url", $url)
    ->isNotNull('nls.handler')
    ->execute()
    ->fetchField();
  return (bool) $result;
}

/**
 * Get a list of vinculum-handlers and their attributes.
 *
 * @return Array
 * An array of vinculum handler objects. Each handler has the properties:
  * - module   The system-name of the module.
  * - protocol The human-readable name of the vinculum protocol provided.
  * - weight   The weight of the module.
 */
function vinculum_get_handler($handler = NULL) {
  $handlers = vinculum_load_all_handlers();
  if (is_null($handler)) {
    return $handlers;
  }
  elseif (isset($handlers[$handler])) {
    return $handlers[$handler];
  }
  else {
    return NULL;
  }
}

/**
 * Fetch a list of all the vinculum handlers.
 *
 * @param optional Boolean $reset_cache
 * Set to TRUE to force a relooad of the handlers from their hooks.
 *
 * @return Array
 * A list of vinculum handlers, ordered according to the priority from most
 * important to least. Each handler has the properties:
 * - module   The system-name of the module.
 * - protocol The human-readable name of the vinculum protocol provided.
 * - weight   The weight of the module.
 */
function vinculum_load_all_handlers($reset_cache = FALSE) {
  if (!($reset_cache) && $cache = cache_get('vinculum_handlers')) {
    $handlers = $cache->data;
  }
  else {
    // Invoke hook_vinculum_handler().
    // module_invoke_all() will order the results by module-weight: no further
    // sorting required.
    $vinculum_handler_modules = module_implements('vinculum_handler');

    $weights = _vinculum_get_module_weights($vinculum_handler_modules);
    $handlers = array();
    foreach ($vinculum_handler_modules as $module) {
      $callback = "{$module}_vinculum_handler";

      $handlers[$module] = (object) $callback();
      $handlers[$module]->module = $module;
      $handlers[$module]->weight = $weights[$module];
    }
    cache_set('vinculum_handlers', $handlers);
  }

  return $handlers;
}

/**
 * Set the weights of modules.
 *
 * @param Array $weights
 * Array of module weights, keyed by the system-name of the module.
 */
function vinculum_set_weights($weights) {
  foreach ($weights as $module => $weight) {
    _vinculum_set_weight($module, $weight);
  }

  // We need to rebuild the module-weight cache when this is called.
  cache_clear_all('hook_info',         'cache_bootstrap');
  cache_clear_all('module_implements', 'cache_bootstrap');
  cache_clear_all('system_list',       'cache_bootstrap');
  cache_clear_all('vinculum_handlers', 'cache');
}



/**********************************************************
 * Private API handlers.
 *********************************************************/

/**
 * Fetch the node-settings (whether send/receive is enabled) for one or more
 * nodes.
 *
 * @param Int|Array $nids
 * Either a single node nid, or an array of node nids.
 *
 * @return Array
 * An array of settings objects (each with the properties 'nid', 'send' and
 * 'receive'), indexed by node nid.
 */
function _vinculum_node_get_settings($nids) {
  if (is_numeric($nids)) {
    $nids = array($nids);
  }

  $result = db_select('node_vinculum_settings', 'nls', array('target' => 'slave'))
    ->fields('nls', array('nid', 'send', 'receive'))
    ->condition("nls.nid", $nids, 'IN')
    ->execute()
    ->fetchAllAssoc('nid');

  return $result;
}

/**
 * Save the vinculum-settings for a node, scan the node for links, and fire off
 * vinculums as needed.
 */
function _vinculum_node_save($node) {
  // If a custom send/receive setting has not been provided, use the default
  // setting for this node-type.
  $settings = array(
    'send'    => isset($node->vinculum_send)    ? (bool) $node->vinculum_send    : variable_get("vinculum_send_{$node->type}", TRUE),
    'receive' => isset($node->vinculum_receive) ? (bool) $node->vinculum_receive : variable_get("vinculum_receive_{$node->type}", TRUE),
  );

  // Update the flags in {node_vinculum_settings}.
  db_merge('node_vinculum_settings')
    ->key(array(
      'nid' => $node->nid,
      ))
    ->fields(array(
      // Cast the booleans to an int, to match the db data-type.
      'send'    => (int) $settings['send'],
      'receive' => (int) $settings['receive'],
    ))
    ->execute();


  if ($settings['send']) {
    // TODO: do this now or later?
    vinculum_node_process($node);
  }
}

/**
 * Get the module-weights for a set of modules (used to fetch the weights of
 * the vinculum-handler modules).
 *
 * @param Array $modules
 * An array of module names.
 *
 * @return Array
 * An array of module-weights, keyed by module name.
 */
function _vinculum_get_module_weights($modules) {
  if (!is_array($modules) || empty($modules)) {
    return array();
  }

  $result = db_select('system', 's', array('target' => 'slave'))
    ->fields('s', array('name', 'weight'))
    ->condition('s.type', 'module')
    ->condition("s.name", $modules, 'IN')
    ->orderBy('weight', 'ASC')
    ->orderBy('filename', 'ASC')
    ->execute()
    ->fetchAllAssoc('name');

  $weights = array();
  foreach ($result as $module => $row) {
    $weights[$module] = $row->weight;
  }
  return $weights;
}

/**
 * Set the weight of a module.
 *
 * @param String $module
 * The system name of the module.
 * @param Int $weight
 * The new weight to set.
 */
function _vinculum_set_weight($module, $weight) {
  db_merge('system')
    ->key(array(
      'type' => 'module',
      'name' => $module,
      ))
    ->fields(array(
      'weight' => $weight
    ))
    ->execute();
}

/**
 * Helper function to generate standard vinculum permission list for a given type.
 *
 * @param $type
 *   The machine-readable name of the node type.
 * @return array
 *   An array of permission names and descriptions.
 */
function _vinculum_list_permissions($type) {
  $info = node_type_get_type($type);
  $type = check_plain($info->type);

  // Build standard list of node permissions for this type.
  $perms = array(
    "configure $type vinculums" => array(
      'title' => t('%type_name: Configure vinculums', array('%type_name' => $info->name)),
      'description' => t('This is only available to users who already have permission to edit the content.'),
    ),
  );

  return $perms;
}

/**
 * Extract text from a single field-API field.
 *
 * @param Object $node
 *   A drupal node.
 *
 * @return String
 *   The text found in the node's body field.
 */
function _vinculum_extract_text($node) {
  $langcode = field_language('node', $node, 'body');

  // If body is empty, abort early.
  if (!isset($node->body[$langcode][0])) {
    return '';
  }

  $item = $node->body[$langcode][0];

  // Use the API to generate a renderable array.  This allows all the regular
  // field-alter hooks to fire, so we get the same text as it would be rendered
  // on the page.
  $field = field_view_value('node', $node, 'body', $item);
  $text = drupal_render($field);

  return $text;
}

/**
 * Extract all the external URLs from a single string.
 */
function _vinculum_extract_urls($text) {
  // Check for the href value of explicit <a> tags, and remove the text found
  // within the <a> tags (because the "Convert URLs into links" filter may
  // shorten <a> text, making uniqueness difficult).
  $pattern = "#<a [^>]*?href=([\"'])([^\\1]+?)\\1[^>]*?>.*?</a>#ms";
  preg_match_all($pattern, $text, $matches);

  // Matches:
  // 0 = The full <a>...</a> tag.
  // 1 = The initial quote mark (used purely for back-referencing)
  // 2 = The value of the href attribute.
  $links = $matches[2];

  // Remove the <a>...</a> tags which have just been captured.
  $text = preg_replace($pattern, '', $text);

  // Regexp is stolen from trackback.module ;)
  preg_match_all("/(http|https):\/\/[a-zA-Z0-9@:%_~#?&=.,\/;-]*[a-zA-Z0-9@:%_~#&=\/;-]/", $text, $matches);

  // TODO: check that the URLs are external, and not local FQDN?

  $links = array_merge($links, $matches[0]);
  return array_unique($links);
}