Hook for altering parsed xml

Problem/Motivation

Generally, there are xml elements and attributes returned by the appliance that are being ignored by the google_appliance module. In my case, I'd like to decorate my search results based on mime type, which is returned as an attribute for file urls.

Proposed resolution

The simplest way to do this is to continue extending the google_appliance_parse_device_response_xml function in the .module file (e.g. as was done for keywords). A more general solution would be to provide a hook for modifying the results array.

The general solution would be more flexible. It would allow for removing results, parsing custom xml elements, and interoperability with multiple (future?) versions of google appliance that might have different DTDs.

Remaining tasks

A patch is attached. But is this the best design?

Also, test, and document.

User interface changes

None.

API changes

hook_google_appliance_results_alter(&$results, $simple_xml)

Frankly, I don't know how hooks get documented, so here is my example usage for adding a 'mime' element to each result that has the 'MIME' attribute.

/*
 * @Implements hook_google_appliance_results_alter
 *
 * @arg &$results
 *    results parsed so far, to be altered
 * @arg &$simple_xml
 *    a simplexml object containing the full results returned from the appliance
 */
function local_mods_google_appliance_results_alter(&$results, $simple_xml) {
  foreach ($results['entry'] as &$res_array) {
    $abs_url = $res_array['abs_url'];
    if ($url_element = $simple_xml->xpath("//U[text()='$abs_url']")) {
      if ($res_element = $url_element[0]->xpath("parent::*")) {
        $res_array['mime'] = $res_element[0]['MIME'];
      }
    }
  }
}