#
# 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
  'departments' : array of dictionaries (serialized Departments), 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

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)

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

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

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

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
