STRUCTS

#
# Copyright (C) 2013 Canonical Ltd
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License version 3 as
# published by the Free Software Foundation.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>.
#

-----------------------------------------------------------------------------
This document describes data structures that are serialized and exchanged by
middleware.
-----------------------------------------------------------------------------

Result (returned by serialize()):
=================================
'attrs' : {
    'uri' : string
    'title' : string
    'art' : string
    'dnd_uri' : string
    + any custom key-value attribute added by scope author.
},
'internal' : {
    'result' : dictionary (serialized Result), optional
    'flags'  : integer, optional (activation/preview flags defined by ResultImpl::Flags enum)
    'origin' : string (scope id)
}

CategorisedResult (returned by serialize()):
=======================================
'attrs' : {
    // all Result's attributes
},
'internal' : {
    'cat_id' : string
    + all Result's internal values
}

Category (returned by serialize()):
=====================================
 'id' : string
 'title' : string
 'icon' : string
 'renderer_template' : string

Department (returned by serialize()):
=====================================
  'query'       : dictionary (serialized Query)
  'label'       : string
  'alt_label'   : string, optional
  'departments' : array of dictionaries (serialized Departments), optional
  'has_subdepartments' : bool (optional)

ScopeMetadata (returned by serialize()):
=====================================
 'scope_id'              : string
 'proxy'                 : dictionary
    'identity'           : string
    'endpoint'           : string
 'display_name'          : string
 'description'           : string
 'scope_dir'             : string, optional
 'art'                   : string, optional
 'icon'                  : string, optional
 'search_hint'           : string, optional
 'hot_key'               : string, optional
 'invisible'             : bool, optional
 'appearance_attributes' : dictionary, optional
 'results_ttl_type'      : int, optional
 'settings_definitions'  : dictionary, optional
 'location_data_needed'  : bool, optional
 'child_scopes'          : array of strings, optional
 'version'               : int, optional
 'keywords'              : set of strings, optional
 'is_aggregator'         : bool, optional

Query (returned by serialize())
===============================
 'scope'         : string
 'query_string'  : string
 'department_id' : string
 'filter_state'  : dictionary (serialized FilterState)

Link (returned by serialize())
==============================
 'label'      : string
 'query'      : Query

Annotation (returned by serialize())
====================================
 'type'       : string
 'label'      : string, optional
 'icon'       : string, optional
 'links'      : array of Links

FilterState (returned by serialize())
=====================================
  filter_id   : Variant (arbitrary, depends on filter type)

FilterGroup
===========
  'id'    : string
  'label' : string

FilterOption
============
 'id'     : string
 'label'  : string

OptionSelectorFilter
====================
 'id'           : string
 'filter_type'  : string
 'display_hints': int, optional
 'filter_group' : string, optional

OptionSelectorFilter (FilterBase)
=================================
 'id'           : string
 'filter_type'  : "option_selector"
 'label'        : string
 'multi_select' : bool
 'options'      : array of FilterOption

RangeInputFilter
================
 'id'                  : string
 'default_start_value' : variant (int, double, null)
 'default_end_value'   : variant (int, double, null)
 'start_prefix_label'  : string
 'start_postfix_label' : string
 'end_prefix_label'    : string
 'end_postfix_label'   : string
 'central_label'       : string
 'filter_group' : string, optional

Filters
=======
 'filter'       : array of filters (implementations of FilterBase)

PreviewResult (returned by serialize())
=======================================
 'id'         : string
 'type'       : string
 'attributes' : dict
 'components' : dict

PushRequest (capnproto structure)
=================================
 result : dictionary with:
                "category" and/or
                "result" or
                "annotation" or
                "departments" and "current_department" or
                "columns"
                key and
  serialized Category / CategorisedResult / Annotation / DepartmentList / ColumnLayoutList respectively.

ActivationResponse (returned by serialize())
============================================
 'status'         : int (corresponds to ActivationResponse::Status enum)
 'scope_data'     : variant
 'query'          : variant (optional)
 'updated_result' : variant (optional)
 'updated_widgets': variant (optional)

QueryMetadata (returned by serialize())
=======================================
 'type'                  : string (metadata type)
 'locale'                : string
 'form_factor'           : string
 'hints'                 : dict
 'internet_connectivity' : bool (optional)

SearchMetadata (returned by serialize())
========================================
  all QueryMetadata attributes
  'cardinality' : int
  'location'    : dict

ActionMetadata (returned by serialize())
========================================
  all QueryMetadata attributes
  'scope_data'  : variant

CannedQuery (returned by serialize())
=====================================
 'scope'         : string
 'query_string'  : string
 'department_id' : string
 'filter_state'  : variant
 'data'          : variant (optional)