modules/geonames/geonames.module

<?php
// $Id

/**
 * @file
 *   GeoNames API / by Erlend Eide, erlend(|)edesign.no
 *
 * The GeoNames API provides a framework for the GeoNames Services. 
 * 
 * Commercial Services credit cost: http://www.geonames.org/professional-webservices.html
 *
 */
        
/**
 * TODO:
 * - Rewrite logics handling the columns option, and the cache-logics (which currently uses
 *   the columns variable to make somewhat ineffective decisions)
 * - Move/Remove Google Maps functions from the core module, must be improved...
 * - Improve handling of exeptions, verboseness, errmessages etc..
 *
 * - Countries, admin-names, feature codes/classes etc could be cached and made available in a function so
 *   we can run fill($resultobject) or something, and then convert all keys to names...

 * - Standardise how to query information from the local tables (countryinfo, continent_codes, us_states and featurecodes)
 *   (should just use geonames_query() with the proper options... 
 */        
        
        
/**
 * Constants
	* hrmpf...
 */
DEFINE('GEONAMES_COMMERCIAL',      variable_get('geonames_commercial_active', FALSE));
DEFINE('GEONAMES_FREE_SERVER_URL', 'http://ws.geonames.org');
DEFINE('GEONAMES_CACHE',           variable_get('geonames_cache', TRUE));
DEFINE('GEONAMES_CACHE_TABLE',     variable_get('geonames_cache_table', 'cache'));    
DEFINE('GEONAMES_CACHE_LIMIT',     86400 * variable_get('geonames_cache_limit', 90));

require("geonames_config.inc");

/**
 * Implementation of hook_cron()
 */
function geonames_cron() {
  // Update countryinfo table once a month (TODO move this block to somewhere else)...
  $updated = variable_get('geonames_metadata_updated', 0);
  $monthago = time() - 2592000;
  if ($updated < $monthago) {
    geonames_metadata_update();
  } 
}

/**
 * Update the metadata tables (Countryinfo and Featurecodes)
 */
function geonames_metadata_update() {
  $file = drupal_http_request("http://download.geonames.org/export/dump/countryInfo.txt?app=drupal");
  if ($file->code == 200) { 
    $lines = split("\n", $file->data);
    foreach ($lines as $line) {
      if (trim($line) != '' && substr($line, 0, 1) != '#') {
        // insert or replace the data
        $a = split("\t", $line);
        if ($a[4] != 'name') {
          db_query("REPLACE INTO {geonames_countryinfo} VALUES('%s', '%s', %d, '%s', '%s', '%s', '%s', '%s', '%s', '%s', '%s', %d)",
                  $a[0], $a[1], $a[2], $a[3], $a[4], $a[5], $a[6], $a[7], $a[8], $a[9], $a[10], $a[11]);
        }
      } 
    }
    watchdog("geonames", "Successfully updated the geonames_countryinfo table");
  }
  else {
    watchdog("geonames", "Failed to updated geonames_countryinfo table", WATCHDOG_WARNING);
    $failed = true;
  }
  
  // Feature code tables
  $file = drupal_http_request("http://download.geonames.org/export/dump/featureCodes.txt?app=drupal");
  if ($file->code == 200) { 
    $lines = split("\n", $file->data);
    foreach ($lines as $line) {
      if (trim($line) != '' && substr($line, 0, 1) != '#') {
        // insert or replace the data
        $a = split("\t", $line);
        $b = split("\.", $a[0]);
        $c = array($b[0], $b[1], $a[1], $a[2]);
        db_query("REPLACE INTO {geonames_featurecodes} VALUES('%s', '%s', '%s', '%s')", $c[0], $c[1], $c[2], $c[3]);
      } 
    }
    watchdog("geonames", "Successfully updated the geonames_featurecodes table");
  }
  else {
    watchdog("geonames", "Failed to updated geonames_featurecodes table", WATCHDOG_WARNING);
    $failed = true;
  }
  
  if (!$failed) {
    variable_set('geonames_metadata_updated', time());  
  }
}

/**
 * Retrieve featureinfo
 *
 * @param 
 *   A string feature code 
 */
function geonames_featureinfo($code) {
  $code = check_plain($code);
  $result = db_fetch_array(db_query("SELECT * FROM {geonames_featurecodes} WHERE code = '%s'", $code));
  return $result;
}

/**
 * Retrieve Country Info
 *
 * @param 
 *   A string iso2 country code or country name
 */
function geonames_countryinfo($param) {
  $param = check_plain($param);
  $result = db_fetch_array(db_query("SELECT * FROM {geonames_countryinfo} WHERE iso_alpha2 = '%s' OR name = '%s'", $param, $param));
  return $result;
}

/**
 * Retrieve Country Info
 */
function geonames_countries($param = NULL, $reset = FALSE) {
  if (is_array($param)) {
    $type = key($param);
    $parameter = $param[$type];
  }

  if (($cache = cache_get('geonames_countries'. $type)) && !empty($cache->data) && !$reset) {
    $countries = $cache->data;
  }
  else {
    switch ($type) {
      case 'continent':
        $result = db_query("SELECT * FROM {geonames_countryinfo} WHERE continent = '%s' ORDER BY name", $parameter);      
        break;
      default:       
        $result = db_query("SELECT * FROM {geonames_countryinfo} ORDER BY name");
    }
    $countries = array();
    while ($a = db_fetch_array($result)) {
      $countries[] = $a;
    }
    cache_set('geonames_countries'. $type, $countries, GEONAMES_CACHE_TABLE, time() + 60 * 60 * 1); // Cache for 1 hour
  }
  return $countries;
}

/**
 * Returns the continent codes
 *
 * @param 
 *   A string, either 'geonameid', 'short' or 'name'
 *
 * @return 
 *   An array with continent information. If parameter key is passed, it is indexed
 */
function geonames_continent_codes($key = NULL) {
  $continent_codes = array(
    array('short' => 'AF', 'name' => 'Africa'        , 'geonameid' => '6255146'),
    array('short' => 'AS', 'name' => 'Asia'          , 'geonameid' => '6255147'),
    array('short' => 'EU', 'name' => 'Europe'        , 'geonameid' => '6255148'),
    array('short' => 'NA', 'name' => 'North America' , 'geonameid' => '6255149'),
    array('short' => 'OC', 'name' => 'Oceania'       , 'geonameid' => '6255151'),
    array('short' => 'SA', 'name' => 'South America' , 'geonameid' => '6255150'),
    array('short' => 'AN', 'name' => 'Antarctica'    , 'geonameid' => '6255152'),
  );
  if ($key == 'geonameid') {
    // Order with geonamesid as key
    foreach ($continent_codes as $c) {
      $codes[$c['geonameid']] = array('short' => $c['short'], 'name' => $c['name']);
    }
  }
  elseif ($key == 'short') {
    // Order with short as key
    foreach ($continent_codes as $c) {
      $codes[$c['short']] = array('geonameid' => $c['geonameid'], 'name' => $c['name']);
    }
  }
  elseif ($key == 'name') {
    // Order with short as key
    foreach ($continent_codes as $c) {
      $codes[$c['name']] = array('geonameid' => $c['geonameid'], 'short' => $c['short']);
    }
  }
  else {
    $codes = $continent_codes;
  }
  return $codes;
}

/**
 * Return Info about US States
 */
function geonames_us_states($state = NULL) {
  $states = array(
   'DC' => 'District of Columbia',
   'AK' => 'Alaska',
   'AL' => 'Alabama',
   'AR' => 'Arkansas',
   'AZ' => 'Arizona',
   'CA' => 'California',
   'CO' => 'Colorado',
   'CT' => 'Connecticut',
   'DE' => 'Delaware',
   'FL' => 'Florida',
   'GA' => 'Georgia',
   'HI' => 'Hawaii',
   'IA' => 'Iowa',
   'ID' => 'Idaho',
   'IL' => 'Illinois',
   'IN' => 'Indiana',
   'KS' => 'Kansas',
   'KY' => 'Kentucky',
   'LA' => 'Louisiana',
   'MA' => 'Massachusetts',
   'MD' => 'Maryland',
   'ME' => 'Maine',
   'MI' => 'Michigan',
   'MN' => 'Minnesota',
   'MO' => 'Missouri',
   'MS' => 'Mississippi',
   'MT' => 'Montana',
   'NC' => 'North Carolina',
   'ND' => 'North Dakota',
   'NE' => 'Nebraska',
   'NH' => 'New Hampshire',
   'NJ' => 'New Jersey',
   'NM' => 'New Mexico',
   'NV' => 'Nevada',
   'NY' => 'New York',
   'OH' => 'Ohio',
   'OK' => 'Oklahoma',
   'OR' => 'Oregon',
   'PA' => 'Pennsylvania',
   'RI' => 'Rhode Island',
   'SC' => 'South Carolina',
   'SD' => 'South Dakota',
   'TN' => 'Tennessee',
   'TX' => 'Texas',
   'UT' => 'Utah',
   'VA' => 'Virginia',
   'VT' => 'Vermont',
   'WA' => 'Washington',
   'WI' => 'Wisconsin',
   'WV' => 'West Virginia',
   'WY' => 'Wyoming',
 );
  return ($state) ? $states[$state] : $states;
} 

/**
 * GeoNames API function
 *
 * See http://www.geonames.org/export/geonames-search.html for full docs.
 * NOTE: q (in GeoNames docs) = query (API), all other parameters are
 * equivalently named
 *
 * @param $service
 *   string: name of service
 *
 * @param $query
 *   associative array with query - optional for some services, mandatory for others
 *
 * @param $columns
 *   optional array: returns only the specified columns, ordered
 *
 * @return
 *     result object (or FALSE on failure) 
 */
function geonames_query($service, $query = array(), $options = NULL) {
//function geonames_query($service, $query = array(), $columns = FALSE) {

  if ($query == NULL || $query == FALSE || $query == '') {
    $query = array();
  }
  else if (!is_array($query)) {
    return FALSE;
  }
    
  // start timer
  $time_start = microtime(TRUE);                           

  // verify that service exists
  $services = geonames_config('services');
  if (!in_array($service, $services)) {
    drupal_set_message(t('GeoNames API: Unknown Service <b>') . $service .'</b>');
    return false;
  };

  // make query and options case insensitive 
  $query = array_change_key_case($query);        
  if (is_array($options)) {
    $options = array_change_key_case($options);
  }
    
  // remove empty-value parameters from query
  foreach ($query as $key => $val) {
    if (empty($val)) {
      unset($query[$key]);
    }
  }
    
  // add default query parameters to query
  $query_defaults = geonames_config($service, 'query_defaults');
  if (is_array($query_defaults)) {
    $query = array_merge($query_defaults, $query);
  }
    
  // check if the query contains the required parameteres
  if (!geonames_query_required_parameters_set($service, $query, geonames_config($service, 'required_parameters_type'))) {
    return FALSE;
  }

  if (NULL != $options) {
    if (!is_array($options)) {
      // options must be an array
      return false;
    }
    if (gettype($options[0]) === string) {
      // Backwards compatibility -- $options was $columns
      $columns = $options;
    }
    if ($options['columns']) {
      $columns = $options['columns'];
      array_walk($columns, '_aw_val_to_lower'); // lowercase all column values
    }
    if ($options['sortby']) {
      $sortby = $options['sortby'];
    }
    if ($options['sortorder']) {
      $sortorder = $options['sortorder'];
    }
  }

  if ($columns == FALSE) {
    // load service defined columns
    $columns = geonames_config($service, 'columns');
  }
  else{
    // If a set of fieldnames is passed, verify that they exist
    if (!$defined_columns = geonames_config($service, 'columns')) {
      $defined_columns = geonames_fields('full', TRUE); // Load full style 
    }
    foreach ($columns as $key => $val) {
      if (!in_array($val, $defined_columns)) {
        // exclude unknown fieldnames
        unset($columns[$key]);
        drupal_set_message(t('Field') .' <i>'. $val .'</i> '. t('is not available for this service, ignoring.'));
      }
    }
  }
  if ($columns) {    
    if (geonames_config($service, 'detect_style')) {
      $query['style'] = geonames_query_detect_style($columns);
    }
    $fields = $columns;
  }
  else {
    // if columns are not specified, use $query['style'], and if that isn't specified - default to short ;)
    $fields = isset($query['style']) ? geonames_fields($query['style'], TRUE) : geonames_fields('short', TRUE); 
  }

  // sort query, so cached queries are more likely to get hit
  asort($query);

  // convert our Query Array to a GeoNames Encoded URI
  if (!$querystring = geonames_prepare_query_string($service, $query)) {
    return FALSE;
  }

  // retrieve results from Cache, or from GeoNames Server
  $cache_geores = geonames_config($service, 'result_cache_prefix') . $querystring;
  $cache_geodat = geonames_config($service, 'data_cache_prefix') . $querystring;
  if (GEONAMES_CACHE) {
    // if columns are passed, get DATA from cache
    if (($columns) && ($cache = cache_get($cache_geodat, GEONAMES_CACHE_TABLE)) && (!empty($cache->data))) { 
      $data = $cache->data;
      $datacache = TRUE;
    }
    // if columns are not passed, get RESULT from cache (fastest) - Don't mess with the parenthesises
    else if ((!$columns) && ($cache = cache_get($cache_geores, GEONAMES_CACHE_TABLE)) && (!empty($cache->data))) { 
      $result = $cache->data;
      if (variable_get('geonames_reveal_cache', TRUE)) {
        $result->request['cached'] = 'result';
      }
    }
  }
    
  // if nothing has been loaded from cache (new query, or cache is disabled) get data from GeoNames
  if (!$result && !$data) {
    $data = file_get_contents(geonames_service_url($service) . $querystring .'&app=drupal');
    if ($data == FALSE) {
      drupal_set_message(t('Fetching data from GeoNames failed... please try again later.'), 'error');
      return FALSE;
    }
    else {
      // increase credit counter if commercial server is used
      if (GEONAMES_COMMERCIAL) {
        geonames_credits_pay($service);
      }
      if (GEONAMES_CACHE && $columns) {
        cache_set($cache_geodat, $data, GEONAMES_CACHE_TABLE, time() + GEONAMES_CACHE_LIMIT);
      }
    }
  }

  if (!is_object($result) && $data) {
    // parse the XML data we have received, and add some more properties to the object
    $result = geonames_parse_xml($data, $fields);
    $result->service            = $service;
    $result->request['url']     = geonames_service_url($service) . $querystring;
    $result->request['bytes']   = strlen($data); 
    $result->query              = $query;
    if (variable_get('geonames_reveal_cache', TRUE) && $datacache) {
      $result->request['cached']= 'data';
    }
    if (geonames_config($service, 'pager')) {
      $result->pager            = _prepare_pager_data($query['maxrows'], $query['startrow'], $result->total_results_count);
    }
    if (GEONAMES_CACHE && !$columns) {
      cache_set($cache_geores, $result, GEONAMES_CACHE_TABLE, time() + GEONAMES_CACHE_LIMIT);
    }
        
    // If sorting parameters are passed
    if ($sortby || $sortorder) {
      _geonames_sort($result->results, $sortby, $sortorder);
    }
  }  

  $result->request['seconds'] = microtime(TRUE) - $time_start; 

  return $result;
}
 
/**
 * Returns the Service URL for the specified service
 *
 * @param $service
 *   string, i.e. 'search' for the search service
 * @return url (string)
 */
function geonames_service_url($service) {
  $service_path = geonames_config($service, 'service_path');
  if ($service_path) {
    return (GEONAMES_COMMERCIAL) 
      ?  variable_get('geonames_commercial_server', '') .'/'. $service_path .'?username='. variable_get('geonames_commercial_username', '') .'&'
      : GEONAMES_FREE_SERVER_URL .'/'. $service_path .'?';
  }
  return false;
}

/**
 * Prepare the Query String
 * 
 * This function verifies the integrity of the query array, and builds the parts 
 * using geonames_prepare_query_string_element
 *
 * @param $query
 *   array with query properties
 *
 * @return 
 *   URL Query String
 *
 * @see
 *   geonames_prepare_query_string_element
 */
function geonames_prepare_query_string($service, $query) {
  foreach ($query as $key => $val) {
    if (is_array($val)) { 
      // Verify that the parameter is allowed to be an array;
      if ($arrpar = geonames_config($service, 'array_parameters')) {
        if (!in_array($key, $arrpar)) {
          return FALSE;
        }
      }
    }
    else {
      $val = array($val); // for convenience in the upcoming foreach loop ;)
    }
    // build query string for all elements
    foreach ($val as $value) {
      $querystring .= geonames_prepare_query_string_element($service, $key, $value);    
    }        
  }
  return ($querystring ? substr($querystring, 1, strlen($querystring)) : '&'); // Remove presceding & -- for empty queries, add a harmless & ;)
}

/**
 * Build Query String Elements
 *
 * The function changes keys and values from lowercase and 
 * mixed, to the GeoNames format. The function also filters
 * out unwanted/disallowed elements from the query.
 *
 * @param $service
 *   string (ex: 'search' or 'nearbyplace')
 *
 * @see
 *   geonames_prepare_query_string 
 */
function geonames_prepare_query_string_element($service, $key, $val) { 
  $parameters = geonames_config($service, 'allowed_parameters');
  $keys = array_keys($parameters); 

  // is the parameter allowed for this service? else just skip it
  if (in_array($key, $keys)) {
    // radius is always Maximum 300 km
    if ($key == 'radius' && $val > 300) {
      $val = 300;
    }    
    // uppercase values
    if ($key == 'style' || $key == 'featureclass' || $key == 'featurecode') {
      $val = strtoupper($val);
    }
    // lowercase values
    if ($key == 'lang') {
      $val = strtolower($val);
    }
    // url encode string parameters that may contain special characters or spaces
    if ($key == 'name' || $key == 'query') {
      $val = urlencode($val); 
    }
    // switch to GeoNames style parameter names
    $key = $parameters[$key]; 
    if ($val != '') {
      $qs_element = "&$key=$val";
    }
  }
  return $qs_element;
}

/**
 * Checks if Required Parameters are Set for $service/$query
 *
 * @param $service
 *   string, (for example search or nearbyplace)
 * @param $query
 *   array (query array)
 * @param $single
 *     true = one of the paramters required
 *   false = all of the parameters required
 * @return
 *   boolean TRUE/FALSE
 */ 
function geonames_query_required_parameters_set($service, $query, $single = 'single') {    
  $required_parameters = geonames_config($service, 'required_parameters'); 
  if (!is_array($required_parameters)) {
    return TRUE; // There are no required parameters ;)
  }
  // If the required parameters consists of a set of arrays (several combinations)
  // one of the sets must return true 
  if (!is_array($required_parameters[0])) {
    // Convert to array of array
    $required_parameters = array($required_parameters);
  }
  
  $set = false;
  foreach ($required_parameters as $rp) {
    if ($set) {
      return $set; // no need to keep working if we have a confirmed configuration
    }
    $count = 0;
    switch ($single) {
      case 'single':
        // One of the defined parameters are required
        foreach ($rp as $param) {
          if (!$set) {
            $set = ($query[$param]) ? TRUE : FALSE;
          }
        }
        break; 
        
      case 'all':
        // All of the defined parameters required
        foreach ($rp as $param) {
          if ($query[$param]) {
            $count = $count + 1;
          }
        }
        $set = (count($rp) == $count) ? TRUE : FALSE;
        break;
    } // end switch ($single)        
  } // end foreach required parameter
  return $set;
}

/**
 * Parser for the GeoNames Search Service XML Response
 * 
 *   If fields is specified, the return object will only return the fields
 *   you ask for, in the specified order.
 *
 * @param $data 
 *   geonames XML document
 *
 * @param $fields
 *   optional array of fields that the returned object must contain
 *
 * @return
 *   $result object 
 */
function geonames_parse_xml($data, $columns = FALSE) {
  // temporary solution; get stuff from XML tag to distinguish between pay-service and free service
  preg_match('/<\?xml version="(.*)" encoding="([a-zA-Z\-0-9]*)"(.*)\?>/', $data, $regs);
  if ($regs[3]) {
    $subreg = explode('"', $regs[3]);
    $result->standalone = $subreg[1];
  }

  $xml = new SimpleXMLElement($data);
  if (isset($xml) && is_array($xml->status)) {
    $result->status['message'] = (string) $xml->status['message'];
    $result->status['value']   = (string) $xml->status['value'];
  } 
  else {  
    $field_template = array();
    $field_actual = array();
    foreach ($xml->children() as $entry) {
      $fields = array();
      $entryhasvalues = FALSE;
      // create structure template based on the $columns passed, this ensures the order is like specified
      foreach ($columns as $columnname) {
        $fields[$columnname] = '';
      }
      if (!$field_template) {
        // store template on first loop only
        $field_template = array_keys($fields);
      }
      // build a list of all the attributes in the entry
      foreach ($entry->children() as $key => $field) {
        $fieldname = strtolower($key);
        $field_actual[$fieldname] = '';
        // TODO!! Either in_array or $[]... "search" needs in_array...
        if ((!$columns)  || in_array($fieldname, $columns) || $fieldname = 'timezone') { 
          $entryhasvalues = TRUE;
          $fields[$fieldname] = (string) $field;
        // if timezone is not requested, don't return it! ;)
          if ($fieldname == 'timezone' && $columns && !in_array($fieldname, $columns)) {
            unset($fields['timezone']);
          }
          foreach ($field->attributes() as $attr) { 
            $attrname = strtolower($attr->getName());
            $field_actual[$attrname] = '';
            $fields[$attrname] = (string) $attr;
            if ($attrname == 'gmtoffset' && $columns && !in_array($attrname, $columns)) {
              unset($fields['gmtoffset']);
            }
            if ($attrname == 'dstoffset' && $columns && !in_array($attrname, $columns)) {
              unset($fields['dstoffset']);
            }
          }
        }
      }

      // clean out field names that weren't in the result set from GeoNames
      if (!$field_diff) {
        $field_diff = array_diff($field_template, array_keys($field_actual));
        if (is_array($field_diff)) {
          $field_clean == true;
        }
      }
      // Clean out the container elements that are not in the result set from geonames!
      elseif ($field_clean) {
        foreach ($field_diff as $remove_field) {
          unset($fields[$remove_field]);
        }
      }
      
      if ($entryhasvalues) {
        $result->results[] = $fields;
      }    
    }
    
    $result->total_results_count = ($xml->totalResultsCount) ? (string) $xml->totalResultsCount : count($result->results);
  }
  return $result;        
}

/**
 * Commercial Service: Increase the Credits Counter ;)
 */
function geonames_credits_pay($service) {
  $cost =  (is_numeric($service)) ? $service : geonames_config($service, 'credit_cost');
  variable_set('geonames_commercial_credits', $cost + variable_get('geonames_commercial_credits', 0));
}

/**
 * Commercial Service: Reset Credits Counter
 */
function geonames_credits_reset($adminpage = TRUE) {
  variable_set('geonames_commercial_credits', 0);
  variable_set('geonames_commercial_credits_since', time());
  if ($adminpage) {
    drupal_set_message('Credits and time reset.');
    drupal_goto('admin/settings/geonames');
  }
}

/**
 * Clear the Results and Data Cache
 */
function geonames_cache_clear($adminpage = TRUE) {
  $res_cache_prefixes = geonames_config('all values', 'result_cache_prefix');
  $dat_cache_prefixes = geonames_config('all values', 'data_cache_prefix');
  $cache_prefixes = array_merge($res_cache_prefixes, $dat_cache_prefixes); 
  foreach ($cache_prefixes as $prefix) {
    cache_clear_all($prefix, GEONAMES_CACHE_TABLE, TRUE);
  }
  if ($adminpage) {
    drupal_set_message('Cache cleared.');
    drupal_goto('admin/settings/geonames');
  }
}

/**
 * Return the Number of Items Currently in the Cache
 */
function _geonames_cache_items() {
  $res_cache_prefixes = geonames_config('all values', 'result_cache_prefix');
  $dat_cache_prefixes = geonames_config('all values', 'data_cache_prefix');
  $cache_prefixes = array_merge($res_cache_prefixes, $dat_cache_prefixes); 
  foreach ($cache_prefixes as $prefix) {
    $where .= ($where) ? ' OR ' : '';
    $where .= " cid LIKE '". $prefix ."%' ";
  }
  $cache = db_fetch_object(db_query("SELECT count(*) as items FROM {%s} WHERE $where", GEONAMES_CACHE_TABLE));
  return $cache->items;
}

/**
 * Implementation of hook_menu().
 */
function geonames_menu() {
  $items['admin/settings/geonames'] = array(
    'type' => MENU_NORMAL_ITEM,
    'title' => t('GeoNames'),
    'access arguments' => array('administer site configuration'),
    'page callback' => 'drupal_get_form',
    'page arguments' => array('geonames_admin_settings'),
    'description' => t('GeoNames Configuration.'),
  );
  $items['admin/settings/geonames/clear_cache'] = array(
    'type' => MENU_CALLBACK,
    'access arguments' => array('administer site configuration'),
    'page callback' => 'geonames_cache_clear',
    'page arguments' => TRUE,
  );
  $items['admin/settings/geonames/reset_credits'] = array(
    'type' => MENU_CALLBACK,
    'access arguments' => array('administer site configuration'),
    'page callback' => 'geonames_credits_reset',
    'page arguments' => TRUE,
  );
		$docpath = variable_get('geonames_documentation_path', 'geonames/docs');
  $items[$docpath] = array(
		  'title' => t('Geonames Docs'),
    'access arguments' => array('geonames docs'),
    'page callback' => 'geonames_docs',
				'page arguments' => array(),
  );
  return $items;
} 

function geonames_menu_link() {
  
}

/**
 * Implementation of hook_access().
 */
function geonames_access($op, $node) {
  global $user;
  if ($op == 'view') {
    return (user_access('geonames docs'));
  }
}

/**
 * Implementation of hook_perm().
 */
function geonames_perm() {
  return array(
    'geonames docs',
  );
}

/**
 * Documentation pages is a form, stupid but it works for now :)) 
 */
function geonames_docs() {
  $page = '<div>';
		$page .= '<div class="messages">'. t('Syntax: $result = geonames_query($service, $query, $options)') .'</div>';
  $page .= '</div>';

  $element = array(
		  '#collapsible' => true,
				'#collapsed' => true,
    '#title' => t('Parameter: $service (string)'),
				'#value' => '<div>The "Usage Instructions for Installed Services" below, lists all the currently installed services available on your system. Please look there for details on the various services.</div>',
		);
  $page .= theme('fieldset', $element);

  $element = array(
		  '#collapsible' => true,
				'#collapsed' => true,
    '#title' => t('Parameter: $query (associative array)'),
				'#value' => '<div>Queries (query parameters) are defined as associative arrays, as the one above. For a list of allowed query parameters, please see the specific service under "Usage Instructions for Installed Services".'.'<div class="messages">'. t('Example: $query = array(\'lat\' => 59.95, \'lng\' => 10.77)') .'</div>'.'This query can be used with all services that require the parameters lat and lng, for example Find Nearby Place Name.<br /><br />
        The query parameters are usually integers (numbers) or strings (text), but for a few services they are allowed to be arrays (multiple values) in order to be able to pass several values of the same type (for instance countries or featurecodes), in the example below we pass on two countries.'.'<div class="messages">'. t('Example: $query = array(\'name\' => \'Holmen\', \'country\' => array(\'NO\',\'SE\'))') .'</div>If you use this query with the \'search\' service (GeoNames Fulltext Search), you will find places with the name <i>Holmen</i> in <i>Norway</i> or <i>Sweden</i></div>',
		);
  $page .= theme('fieldset', $element);
		
  $element = array(
		  '#collapsible' => true,
				'#collapsed' => true,
    '#title' => t('Parameter: $options (associative array) - optional'),
				'#value' => t('<div>You may use the $option parameter to modify the results. Limit the number of fields returned, order the columns, or sort the rows. The options array has three optional properties: columns, sortby and sortorder (all of them may be used independently).<br /><br /><b>columns</b> is an array of fieldnames ') .'<div class="messages">'. t('Example: $options '."= array('columns' => array('countryname', 'countrycode') )") .'</div>'. t('By passing this option your results will only contain the two columns specified (countryname and countrycode). The result object will also be arranged with your results in the specified order.') . t('<br /><br /><b>sortby</b> is a fieldname (string) ') .'<div class="messages">'. t('Example: $options '."= array('sortby' => 'countryname')") .'</div>'. t('By passing this option your results will be ordered by the countryname.') . t('<br /><br /><b>sortorder</b> is either ASC or DESC (string) ') .'<div class="messages">'. t('Example: $options '."= array('sortorder' => 'DESC')") .'</div>'. t('By passing this option your results will be returned in a descending order (Your list of Countries would start with the letter Z).') . t('<br /><br /><div class="messages">') . t('Multiple Options Example: $options '."= array('sortby' => 'countryname', 'sortorder' => 'DESC')") .'</div>'. t('This option would return your results ordered by Country Name, descending.</div>'),
		);
  $page .= theme('fieldset', $element);

  $element = array(
		  '#collapsible' => true,
				'#collapsed' => true,
    '#title' =>  t('Result: $result (object)'),
				'#value' => '<div>The results object will look something like this: <br />
<pre>
$result->results = array(
  [0] = array(\'name\' => \'Oslo\', ...)                   
  [1] = array(\'name\' => \'Nydalen\', ...)
  ...
) 
$result->total_results_count = integer, number of total results
$result->service = string service name
$result->request = array (
  \'url\' = URL sent to GeoNames server
  \'bytes\' = size of data requested from GeoNames server  
  \'seconds\' = time used for request to GeoNames server
  \'cached\' = if the result is loaded from the cache, this variable is set to the cache type (result or data)
) 
$result->query = array(
  \'lat\' = 23
  \'lng\' = 34
  \'maxrows\' = 10
  ...
)
$result->pager = array() - associative array, only available for some services
$result->standalone = if set to <i>no</i>, the GeoNames commercial service is used
</pre></code>
</div>',
		);
  $page .= theme('fieldset', $element);

  $page .= '<br /><div>'.t(' In the usage instructions below, <b>bold</b> parameters are ') .'<b>'. t('mandatory') .'</b>'. t('. Parameters that are structured like \'key=value\' are default values for parameters, and may be overridden. Items in ') .'<i>' . t('italics') .'</i> '. t('are ') .'<i>' . t('optional parameters') .'</i>. '. t('Services with multiple bold parameters may be one out of two types; single or all - read the instructions carefully. ') .'<br /><br /><h2>'. t('Usage Instructions for Installed Services') .'</h2></div>';

  $services = geonames_config(); // geonames_config('services', 'keys'); 
		// This function used to return the full configuration........ look into how to fix it (fix in other version as well)!

  foreach ($services as $service => $sc) { // service configuration
    $usage = sprintf("<div class=messages>Usage: \$result = geonames_query('%s', \$query, <i>\$options</i>)</div>", $service);

    // Compile the $query part... this is tricky!
    // First, check if the required parameters is an array of arrays (how many times do we have to loop?)
    // count variations of required parameters combinations
    $variations = (is_array($sc['required_parameters'][0])) ? count($sc['required_parameters']) : 1;
        
    $usage_query = '';
    $loops = 0;
    while ($loops < $variations) {

      // Get $rp
      $rp = ($variations > 1) ? $sc['required_parameters'][$loops] : $sc['required_parameters'];

      $usage_query .= ($usage_query) ? '<b>or</b><div style="height: 8px"></div>' : '';
      $usage_query .= '$query = array(';

      $numreqpar = 0; // Count number of request parameters -- used for displaying various strings later
      if ($rp) {
        foreach ($rp as $pmtr) {
          $numreqpar++;
          $usage_query .= '<b>'. $pmtr .'</b>, ';
        }
      }
                
      if ($sc['query_defaults']) {
        foreach ($sc['query_defaults'] as $key => $val) {
          if ($key != 'type') {
            $usage_query .= $key .'='. $val .', ';                        
          }
        }
      }

      if (is_array($sc['allowed_parameters'])) {
        foreach ($sc['allowed_parameters'] as $key => $val) {
          if ((!is_array($rp) || (is_array($rp) && !in_array($key, $rp))) && (!is_array($sc['query_defaults'] || (is_array($sc['query_defaults']) && !in_array($key, array_keys($sc['query_defaults'])))))) {
            if ($key != 'type') {
              $usage_query .= '<i>'. $key .'</i>, ';            
            }
          }
        }
      }

      $query_comments = '';
      if (is_array($sc['array_parameters'])) {
        // Some of the parameters are allowed to be arrays...
        foreach ($sc['array_parameters'] as $arrpar) {
          $query_comments .= sprintf('<li> %s is allowed to be an array of strings</li>', $arrpar);
        }
      }
            
      // strip the last ', ' from the querystring
      if (strstr($usage_query, ',')) { 
        $usage_query = substr($usage_query, 0, strlen($usage_query) - 2);
      }
      if ($sc['required_parameters_type'] == 'single') {
        if ($numreqpar > 1) {
          $query_comments .= '<li> just one of the bold parameters is required </li>';
        }
      }
      if ($sc['required_parameters_type'] == 'all') {
        if ($numreqpar == 2) {
          $query_comments .= '<li> both bold parameters are required </li>';
        }
        else if ($numreqpar > 2) {
          $query_comments .= '<li> all bold parameters are required </li>';        
        }
      }

      // If no comments, add some space with br
      $query_comments = ($query_comments) ? sprintf("<ul>%s</ul>", $query_comments) : '<div style="height: 6px"></div>';
                
      $usage_query .= ($usage_query) ? ')'. $query_comments : '';    

      $loops++;
                
    } // End while loop
                        
    $resultrows = '<div>$result->results = array(';

    if ($sc['columns']) {
      // Columns are defined -- use those
      foreach ($sc['columns'] as $a) {
        $resultrows .= $a .', ';
      }
      $resultrows = substr($resultrows, 0, strlen($resultrows)-2) .')';
    }
    else {
      // Probably short/medium/long/full syntax... TODO this does not work... DEBUG
      $gf = geonames_fields('full', true);
      foreach ($gf as $f) {
        $resultrows .= $f .', ';            
      }
      $resultrows = substr($resultrows, 0, strlen($resultrows)-2) .')';
      $resultrows .= ' -- FULL style';
    }
    $resultrows .= '</div>';
    
    $element = array(
		    '#collapsible' => true,
			  	'#collapsed' => true,
      '#title' => t($sc['service_full_name']),
      '#value' => '<div>Purpose: '. $sc['description'] . $usage . $usage_query . $resultrows .'</div>',
  		);
    $page .= theme('fieldset', $element);

  }
		
  return $page;
}

/**
 * Admin Settings Page
 */
function geonames_admin_settings() {
  $form['geonames_docs_path'] = array(
    '#type' => 'textfield',
    '#title' => t('Path to GeoNames Documentation'),
    '#description' => t('Where do you want the documentation to reside?'),
    '#default_value' => variable_get('geonames_docs_path', 'geonames/docs'),
  );    
  $form['cache'] = array(
    '#type' => 'fieldset',
    '#title' => t('Cache'),
    '#collapsible' => TRUE,
    '#collapsed' => TRUE,
  );
  $form['cache']['clear_cache'] = array(
    '#prefix' => '<div>',
    '#value' => t('There are currently '. _geonames_cache_items() .' items in the cache. ['. l('Clear cache', 'admin/settings/geonames/clear_cache') .']'),
    '#suffix' => '</div>',
  );
  $form['cache']['geonames_cache'] = array(
    '#type' => 'radios',
    '#title' => t('Caching'),
    '#description' => t('Enable unless you have a good reason to disable it.'),
    '#default_value' => variable_get('geonames_cache', TRUE),
    '#options' => array(1 => 'Enabled', 0 => 'Disabled'),
  );     
  $form['cache']['geonames_cache_limit'] = array(
    '#type' => 'textfield',
    '#title' => t('Cache lifetime'),
    '#description' => t('Cache items for ... days'),
    '#default_value' => variable_get('geonames_cache_limit', 14),
  ); 
  $form['cache']['geonames_reveal_cache'] = array(
    '#type' => 'radios',
    '#title' => t('Reveal Cache'),
    '#description' => t("If an item is retrieved from the cache, the") ." request['cached'] ". t("property will be available in the result object if this switch is set to Yes."),
    '#default_value' => variable_get('geonames_reveal_cache', TRUE),
    '#options' => array(1 => 'Yes', 0 => 'No'),
  );     
  $form['cache']['advanced'] = array(
    '#type' => 'fieldset',
    '#title' => t('Database Configuration (Advanced)'),
    '#collapsible' => TRUE,
    '#collapsed' => TRUE,
  );
  $form['cache']['advanced']['leadingtext'] = array(
    '#prefix' => '<div>',
    '#value'  => t("The GeoNames cache grows pretty rapidly, and a large cache table may slow down other cache requests. The overall performance of your site may be improved by setting up a separate table for caching of GeoNames requests. Create the table manually (structure equivalent to Drupal's cache table), prior to changing the table name here."),
       '#suffix' => '</div>'
  );
  $form['cache']['advanced']['geonames_cache_table'] = array(
    '#type' => 'textfield',
    '#title' => t('Database Cache Table'),
    '#description' => t("Defaults to drupal's") ." <i>cache</i> ". t("table."),
    '#default_value' => variable_get('geonames_cache_table', 'cache'),
  ); 
        
  $commercial_collapsed = (variable_get('geonames_commercial_active', FALSE) == TRUE) ? FALSE : TRUE;
  
  $form['commercial'] = array(
    '#type' => 'fieldset',
    '#title' => t('GeoNames Commercial Webservices'),
    '#collapsible' => TRUE,
    '#collapsed' => $commercial_collapsed
  );
  $form['commercial']['leadingtext'] = array(
    '#prefix' => '<div>',
    '#value' => t('You should always support developers of quality services. Increased performance is cheap, and you should afford it.') .' '. t('Visit the') .' '. l('GeoNames Commercial Webservices', 'http://www.geonames.org/professional-webservices.html') .' '. t('page for more information.'),
    '#suffix' => '</div>'
  );
  if (variable_get('geonames_commercial_active', FALSE) == TRUE) {
    // Show the Status and Credits Counter
    if (GEONAMES_COMMERCIAL) {
      $form['commercial']['counter'] = array(
        '#prefix' => '<div><p>',
        '#value' => '<b>'. t('Status') .':</b><br />'. t('You have used') .' <i>'. variable_get('geonames_commercial_credits', 0) .'</i> '. t('credits since') .' '. format_date(variable_get('geonames_commercial_credits_since', 'unknown')) .'. ['. l('Reset', 'admin/settings/geonames/reset_credits')
.']',
        '#suffix' => '</p></div>'
      );
    }
  }
  $form['commercial']['geonames_commercial_active'] = array(
    '#type' => 'radios',
    '#title' => t('GeoNames Commercial Webservices'),
    '#default_value' => variable_get('geonames_commercial_active', 0),
    '#options' => array(1 => 'Enabled', 0 => 'Disabled'),
  );     
  $form['commercial']['geonames_commercial_active_copy'] = array(
    '#type' => 'value',
    '#value' => variable_get('geonames_commercial_active', 0),
  );     
  $form['commercial']['geonames_commercial_server'] = array(
    '#type' => 'textfield',
    '#title' => t('URL to Commercial Service Server'),
    '#description' => 'Example: http://ws.geonames.net - without the trailing slash',
    '#default_value' => variable_get('geonames_commercial_server', 'http://ws.geonames.net'),
  ); 
  $form['commercial']['geonames_commercial_server_copy'] = array(
    '#type' => 'value',
    '#value' => variable_get('geonames_commercial_server', 'http://ws.geonames.net'),
    );
  $form['commercial']['geonames_commercial_username'] = array(
    '#type' => 'textfield',
    '#title' => t('Username'),
    '#default_value' => variable_get('geonames_commercial_username', ''),
  ); 
  $form['commercial']['geonames_commercial_username_copy'] = array(
    '#type' => 'value',
    '#value' => variable_get('geonames_commercial_username', ''),
    );
    
  $form['licencing'] = array(
    '#prefix' => '<ul><li>',
    '#value' => t('Note: You must give credit to ') . l('GeoNames', 'http://www.geonames.org/') . t(' if you are not using the commercial services, for example by including a link to ') . l('their site', 'http://www.geonames.org/') . t('  on your pages. The GeoNames geographical database is released under the') .' '. l('Creative Commons Attribution Licence 3.0', 'http://creativecommons.org/licenses/by/3.0/') .'.',
    '#suffix' => '</li></ul>'
  );

  return system_settings_form($form);
}

/**
 * Admin Settings Page : Validation
 */
function geonames_admin_settings_validate($form_id, $form_values) {
