Api

Version

mediamosa-30

Class

mediamosa_rest_call_asset_search

Code

File: /sites/all/modules/mediamosa/modules/asset/mediamosa_asset.rest.class.inc
<?php

/**
 * URI: /asset
 * Method: GET
 */
class mediamosa_rest_call_asset_search extends mediamosa_rest_call {
  // ------------------------------------------------------------------ Consts.
  // Rest vars;
  const RETURN_ASSET_IDS = 'return_asset_ids';
  const FAV_USER_ID = 'fav_user_id';
  const USER_ID = 'user_id';
  const ACL_USER_ID = 'acl_user_id'; // Alias for user_id.
  const ACL_GROUP_ID = 'acl_group_id';
  const ACL_DOMAIN = 'acl_domain';
  const ACL_REALM = 'acl_realm';
  const GRANTED = 'granted';
  const OPERATOR = 'operator';
  const HIDE_EMPTY_ASSETS = 'hide_empty_assets';
  const COLL_ID = 'coll_id';
  const IS_PUBLIC_LIST = 'is_public_list';
  const BATCH_ID = 'batch_id';
  const CQL = 'cql';
  const SHOW_DELETED = 'show_deleted';
  const SHOW_STILLS = 'show_stills';
  const SHOW_COLLECTIONS = 'show_collections';
  const CALCULATE_TOTAL_COUNT = 'calculate_total_count';
  const VIEW_HIDDEN_METADATA = 'view_hidden_metadata';

  // Aliases, do NOT use in code(!).
  const ALIAS_AUT_USER_ID = 'aut_user_id';
  const ALIAS_AUT_GROUP_ID = 'aut_group_id';
  const ALIAS_AUT_DOMAIN = 'aut_domain';
  const ALIAS_AUT_REALM = 'aut_realm';

  // ------------------------------------------------------------------ Public Functions.
  static public function get_search_params() {
    return array(
      'asset_id' => mediamosa_sdk::TYPE_SEARCH_STRING,
      'owner_id' => mediamosa_sdk::TYPE_SEARCH_STRING,
      'group_id' => mediamosa_sdk::TYPE_SEARCH_STRING,
      'provider_id' => mediamosa_sdk::TYPE_SEARCH_STRING,
      'reference_id' => mediamosa_sdk::TYPE_SEARCH_STRING,
      'videotimestamp' => mediamosa_sdk::TYPE_SEARCH_DATETIME,
      'videotimestampmodified' => mediamosa_sdk::TYPE_SEARCH_DATETIME,
      'mediafile_duration' => mediamosa_sdk::TYPE_SEARCH_STRING,
      'mediafile_container_type' => mediamosa_sdk::TYPE_SEARCH_STRING,
      'changed' => mediamosa_sdk::TYPE_SEARCH_DATETIME,
      'app_id_search' => mediamosa_sdk::TYPE_SEARCH_INT,
      'mime_type' => mediamosa_sdk::TYPE_SEARCH_STRING,
      'filename' => mediamosa_sdk::TYPE_SEARCH_STRING,
      'numofviews' => mediamosa_sdk::TYPE_SEARCH_INT,
      'numofplays' => mediamosa_sdk::TYPE_SEARCH_INT,
    );
  }

  // ------------------------------------------------------------------ Var Setup.
  public function get_var_setup() {
    $a_var_setup = array();

    $a_var_setup = array(
      self::VARS => array(
        self::RETURN_ASSET_IDS => array(
          self::VAR_TYPE => mediamosa_sdk::TYPE_BOOL,
          self::VAR_DESCRIPTION => 'Return only the found asset ids.',
          self::VAR_DEFAULT_VALUE => 'FALSE',
        ),
        self::FAV_USER_ID => array(
          self::VAR_TYPE => mediamosa_sdk::TYPE_USER_ID,
          self::VAR_DESCRIPTION => 'Search within the favorites of this supplied user ID.',
        ),
        self::HIDE_EMPTY_ASSETS => array(
          self::VAR_TYPE => mediamosa_sdk::TYPE_BOOL,
          self::VAR_DESCRIPTION => 'Do not include assets that do not have mediafiles.',
          self::VAR_DEFAULT_VALUE => 'FALSE',
        ),
        self::COLL_ID => array(
          self::VAR_TYPE => mediamosa_sdk::TYPE_COLLECTION_ID,
          self::VAR_DESCRIPTION => 'Search within these collections.',
          self::VAR_IS_ARRAY => self::VAR_IS_ARRAY_YES,
        ),
        self::GRANTED => array(
          self::VAR_TYPE => mediamosa_sdk::TYPE_BOOL,
          self::VAR_DESCRIPTION => "Include a flag on each asset to indicate access. When providing with TRUE, the result will include assets where no access is available. The 'granted' value in the result, indicates if access was granted for the asset.",
          self::VAR_DEFAULT_VALUE => 'TRUE',
        ),
        self::IS_PUBLIC_LIST => array(
          self::VAR_TYPE => mediamosa_sdk::TYPE_BOOL,
          self::VAR_DESCRIPTION => 'Include or hide private assets in result. TRUE: exclude private assets, FALSE: include private assets.',
          self::VAR_DEFAULT_VALUE => 'FALSE',
        ),
        self::IS_APP_ADMIN => array(
          self::VAR_TYPE => mediamosa_sdk::TYPE_BOOL,
          self::VAR_DESCRIPTION => 'Allows seeing unappropriate assets.',
          self::VAR_DEFAULT_VALUE => 'FALSE',
        ),
        self::USER_ID => array(
          self::VAR_TYPE => mediamosa_sdk::TYPE_USER_ID,
          self::VAR_DESCRIPTION => 'Alias for acl_user_id parameter, is chosen above acl_user_id.',
        ),
        self::ACL_USER_ID => array(
          self::VAR_TYPE => mediamosa_sdk::TYPE_USER_ID,
          self::VAR_DESCRIPTION => 'Authentication parameter.',
          self::VAR_ALIAS_FOR => array(self::ALIAS_AUT_USER_ID),
        ),
        self::ACL_GROUP_ID => array(
          self::VAR_TYPE => mediamosa_sdk::TYPE_GROUP_ID,
          self::VAR_DESCRIPTION => 'Authentication parameter.',
          self::VAR_IS_ARRAY => self::VAR_IS_ARRAY_YES,
          self::VAR_DEFAULT_VALUE => array(),
          self::VAR_ALIAS_FOR => array(self::ALIAS_AUT_GROUP_ID),
        ),
        self::ACL_DOMAIN => array(
          self::VAR_TYPE => mediamosa_sdk::TYPE_DOMAIN,
          self::VAR_DESCRIPTION => 'Authentication parameter.',
          self::VAR_ALIAS_FOR => array(self::ALIAS_AUT_DOMAIN),
        ),
        self::ACL_REALM => array(
          self::VAR_TYPE => mediamosa_sdk::TYPE_REALM,
          self::VAR_DESCRIPTION => 'Authentication parameter.',
          self::VAR_ALIAS_FOR => array(self::ALIAS_AUT_REALM),
        ),
        self::BATCH_ID => array(
          self::VAR_TYPE => mediamosa_sdk::TYPE_BATCH_ID,
          self::VAR_DESCRIPTION => 'Search within batch.',
        ),
        self::CQL => array(
          self::VAR_TYPE => mediamosa_sdk::TYPE_CQL_ASSET,
          self::VAR_DESCRIPTION => 'The CQL search string, used for extended and complex search options.',
        ),
        self::SHOW_DELETED => array(
          self::VAR_TYPE => mediamosa_sdk::TYPE_BOOL,
          self::VAR_DESCRIPTION => 'Include deleted assets for OAI. The deleted assets are not complete assets, these assets are empty and are only an indication that they are deleted.',
          self::VAR_DEFAULT_VALUE => 'FALSE',
        ),
        self::SHOW_STILLS => array(
          self::VAR_TYPE => mediamosa_sdk::TYPE_BOOL,
          self::VAR_DESCRIPTION => 'Include stills in output.',
          self::VAR_DEFAULT_VALUE => 'TRUE',
        ),
        self::SHOW_COLLECTIONS => array(
          self::VAR_TYPE => mediamosa_sdk::TYPE_BOOL,
          self::VAR_DESCRIPTION => 'Include collection information of each assets, when available.',
          self::VAR_DEFAULT_VALUE => 'FALSE',
        ),
        self::CALCULATE_TOTAL_COUNT => array(
          self::VAR_TYPE => mediamosa_sdk::TYPE_BOOL,
          self::VAR_DESCRIPTION => "Calculate the number of rows in the complete scope of the search and store it in the header parameter 'item_count_total'. Performance will drasticly improve with value 'FALSE' if you don't need to know the total number of assets in your scope result. If you provide 'FALSE', then 'item_count_total' value in the header will always be the number of items returned, same as 'item_count'.",
          self::VAR_DEFAULT_VALUE => 'TRUE',
        ),
        self::VIEW_HIDDEN_METADATA => array(
          self::VAR_TYPE => mediamosa_sdk::TYPE_BOOL,
          self::VAR_DESCRIPTION => "View hidden metadata.",
          self::VAR_DEFAULT_VALUE => 'FALSE',
        ),

        // Old fasion search params.
        self::OPERATOR => array(
          self::VAR_TYPE => mediamosa_sdk::TYPE_OPERATOR,
          self::VAR_DESCRIPTION => 'For non-CQL search only; provide either OR or AND for search parameters..',
          self::VAR_DEFAULT_VALUE => 'and',
        )
      )
    );

    // Include limit, offset vars.
    $a_var_setup = self::get_var_setup_range($a_var_setup);

    // Include order by.
    $a_var_setup = self::get_var_setup_order_by($a_var_setup);

    // Include default.
    $a_var_setup = self::get_var_setup_default($a_var_setup);

    // Process what we have.
    $a_var_setup = parent::process_rest_args($a_var_setup);

    // If we return only asset ids, then we differ from limit_max.
    $return_asset_ids = $this->get_param_value(self::RETURN_ASSET_IDS);

    if ($return_asset_ids) {
      $a_var_setup = self::get_var_setup_range($a_var_setup, mediamosa_settings::LIMIT_MAX_IDS_ONLY);
    }

    $app_ids = $this->get_param_value_app();

    // Now include metadata search stuff.
    $a_var_setup = mediamosa_core_cql::get_var_setup_search_asset($app_ids, $a_var_setup, self::get_search_params());

    return $a_var_setup;
  }

  // ------------------------------------------------------------------ Override Process Rest Args.
  // Fix for alias of user_id / acl_user_id.
  protected function process_rest_args(array $a_var_setup) {

    // Process input.
    $a_var_setup = parent::process_rest_args($a_var_setup);

    // If user_id is set, override acl_user_id, dont care if acl_user_id is set.
    $user_id = $this->get_param_value(self::USER_ID);

    if ($user_id != '') {
      $this->set_param_value(self::ACL_USER_ID, $user_id);
    }

    // Return the var_setup.
    return $a_var_setup;
  }

  // ------------------------------------------------------------------ Override Validate Rest Args.
  // Override for checking CQL string.
  protected function validate_rest_args(array $var_setup) {

    // Validate first.
    parent::validate_rest_args($var_setup);

    // CQL string needs validation. We do this here.

    // Get app ids.
    $app_ids = $this->get_param_value_app();

    // Now convert the old search parameters to CQL.
    $var_setup_search = mediamosa_core_cql::get_var_setup_search_asset($app_ids, array(), self::get_search_params());

    $a_cql = array();
    $translate_to = array();
    foreach ($var_setup_search[mediamosa_rest_call::VARS] as $param_name => $param) {
      if ($param[mediamosa_rest_call::VAR_TYPE] == mediamosa_sdk::TYPE_SEARCH_MATCH) {
        continue;
      }

      // When provided, then convert.
      if (!self::empty_param($param_name)) {
        $value = $this->get_param_value($param_name);
        $match = $this->get_param_value($param_name . '_match');
        $a_cql[] = mediamosa_core_cql::convert_searchparam_to_cql($param_name, $match, $value, $param[mediamosa_rest_call::PARAM_TYPE], $translate_to);
      }
    }

    $cql = '';
    if (!empty($a_cql)) {

      // CQL must not be set.
      if (!self::empty_param(self::CQL)) {
        throw new mediamosa_exception_error_cql_exclusive();
      }

      // Get the glue operator.
      $operator = $this->get_param_value(self::OPERATOR);

      $cql = implode(' ' . mediamosa_unicode::strtoupper($operator) . ' ', $a_cql);
    }

    // Non CQL parameters.
    $order_by = $this->get_param_value(self::ORDER_BY);
    $order_direction = $this->get_param_value(self::ORDER_DIRECTION);

    // Add possible order by to the CQL.
    if ($order_by != '') {
      if (!self::empty_param(self::CQL)) {
        throw new mediamosa_exception_error_cql_exclusive();
      }

      $cql .= (!empty($cql) ? ' ' : '') . 'sortby ' . $order_by;
      $cql .= (empty($order_direction) ? '' : '/' . (mediamosa_unicode::strtolower($order_direction) == mediamosa_type::ORDER_DIRECTION_ASC ? 'ascending' : 'descending'));
    }
    elseif (empty($a_cql)) {
      // Now normal search params, then take CQL (if any).
      $cql = $this->get_param_value(self::CQL);
    }
    $app_ids = $this->get_param_value_app();
    $error_text = '';

    if (!empty($cql) && !mediamosa_core_cql::verify_asset($cql, $app_ids, $error_text)) {
      throw new mediamosa_exception_error(mediamosa_error::ERRORCODE_CQL_ERROR, array('@error' => $error_text));
    }

    // Save the possible changed CQL.
    $this->set_param_value(self::CQL, $cql);
  }

  // ------------------------------------------------------------------ Do Call.
  public function do_call() {
    $mediamosa = mediamosa::get();

    $app_ids = $this->get_param_value_app();

    // Calculate the total.
    $calculate_total_count = $this->get_param_value(self::CALCULATE_TOTAL_COUNT);

    // View hidden metadata.
    $view_hidden_metadata = $this->get_param_value(self::VIEW_HIDDEN_METADATA);

    // Get CQL.
    $cql = $this->get_param_value(self::CQL);

    // Now search.
    $asset_ids = mediamosa_search::asset(array(
      'app_ids' => $app_ids,
      'cql' => $cql,
      'cql_store_stats' => TRUE,
      'acl_user_id' => $this->get_param_value(self::ACL_USER_ID),
      'acl_group_ids' => $this->get_param_value(self::ACL_GROUP_ID),
      'acl_domain' => $this->get_param_value(self::ACL_DOMAIN),
      'acl_realm' => $this->get_param_value(self::ACL_REALM),

      'batch_id' => $this->get_param_value(self::BATCH_ID),
      'coll_id' => $this->get_param_value(self::COLL_ID),

      'fav_user_id' => $this->get_param_value(self::FAV_USER_ID),

      'granted' => $this->get_param_value(self::GRANTED),
      'is_public_list' => $this->get_param_value(self::IS_PUBLIC_LIST),
      'is_app_admin' => $this->get_param_value(self::IS_APP_ADMIN),
      'hide_empty_assets' => $this->get_param_value(self::HIDE_EMPTY_ASSETS),
      'show_deleted' => $this->get_param_value(self::SHOW_DELETED),
      'calculate_total_count' => $calculate_total_count,

      'limit' => $this->get_param_value_limit(),
      'offset' => $this->get_param_value_offset()
    ));

    // Set the total amount found.
    $mediamosa->item_count_total = $asset_ids['total_count'];

    // Fill response.
    if ($this->get_param_value(self::RETURN_ASSET_IDS)) {
      foreach ($asset_ids['asset_ids'] as $asset_id) {
        $mediamosa->add_item(array('asset_id' => $asset_id));
      }
    }
    else {
      $add_has_streamable_mediafiles = TRUE;

      $items = mediamosa_asset::asset_collect(
        $asset_ids['asset_ids'],
        $app_ids,
        $this->get_param_value(self::ACL_USER_ID),
        $this->get_param_value(self::GRANTED),
        $this->get_param_value(self::ACL_GROUP_ID),
        $this->get_param_value(self::ACL_DOMAIN),
        $this->get_param_value(self::ACL_REALM),
        $this->get_param_value(self::IS_APP_ADMIN),
        $this->get_param_value(self::SHOW_STILLS),
        $this->get_param_value(self::SHOW_COLLECTIONS),
        $add_has_streamable_mediafiles,
        $view_hidden_metadata
      );

      foreach ($items as $item) {
        $mediamosa->add_item($item);
      }
    }
  }
}