Source

scope.bitbucket.org / scope / _sources / services / CookieManager / CookieManager_1_1.txt

=================
CookieManager 1.1
=================

:Generated:  hob rst-doc
:Version:    1.1.1
:Status:     Published

Service
=======

This service can enumerate and remove cookies for a certain domain.

It can currently not add cookies, but this can be achieved through
ECMAScript (document.cookie).

Changelog:
1.0 - First release
1.0.1 - Fixed a bug in RemoveCookie where it would remove all cookies,
        not just in the specified domain.
1.1 - Added AddCookie
1.1.1 - Fixed a bug in GetCookie where the filtering failed.


.. code-block:: c

  service CookieManager
  {
    option (version) = "1.1.1";

  
    command GetCookie(GetCookieArg)       returns (CookieList)     = 1;
    command RemoveCookie(RemoveCookieArg) returns (Default)        = 2;
    command RemoveAllCookies(Default)     returns (Default)        = 3;
    command GetCookieSettings(Default)    returns (CookieSettings) = 4;
    command AddCookie(AddCookieArg)       returns (Default)        = 5;
  }



Commands
========

.. index:: AddCookie

``AddCookie``
-------------

::

  command AddCookie(AddCookieArg) returns (Default) = 5;

Add a new cookie, will overwrite exsisting with same domain/name

@param  domain Name of domain, e.g. "opera.com"
@param  name Name of cookie to add
@param  path (optional, defaults to "/")
@param  value (optional) Cookie value
@param  expires (optional) This is seconds since epoch
@param  isSecure (optional defaults to false) Only use this cookie on secure connections
@param  isHTTPOnly (optional defaults to false) Only use this cookie for HTTP


argument:

.. index:: AddCookieArg

.. code-block:: c

  message AddCookieArg
  {
    /**
     * Domain name of cookie
     */
    required string domain     = 1;
    /**
     * Name of cookie
     */
    required string name       = 2;
    /**
     * Path of cookie, defaults to /
     */
    optional string path       = 3;
    /**
     * Cookie value
     */
    optional string value      = 4;
    /**
     * Expiry time set via seconds since epoch
     */
    optional uint32 expires    = 5;
    /**
     * If true cookie is only accessible via secure connections
     */
    optional bool   isSecure   = 6 [default = false];
    /**
     * If true the cookie is only accessible via HTTP
     */
    optional bool   isHTTPOnly = 7 [default = false];
  }




.. index:: GetCookie

``GetCookie``
-------------

::

  command GetCookie(GetCookieArg) returns (CookieList) = 1;

Retrieve a list of cookies for a given domain.

@param domain Name of domain to look for, e.g. "opera.com"
@param path   Limit cookie list to specified path or subpath.


argument:

.. index:: GetCookieArg

.. code-block:: c

  message GetCookieArg
  {
    required string domain = 1;
    optional string path   = 2;
  }

returns:

.. index:: CookieList

.. code-block:: c

  message CookieList
  {
    repeated Cookie cookieList = 1;
  }

references:

.. index:: Cookie

.. code-block:: c

  message Cookie
  {
    required string domain     = 1;
    required string path       = 2;
    required string name       = 3;
    required string value      = 4;
    /**
     * Expiry time for cookie specified in seconds from epoch (Unix timestamp).
     * A value of 0 means the cookie is expired when the session ends (browser closes).
     */
    required uint32 expires    = 5;
    /**
     * If true the cookie will only be transferred on secure connections (HTTPS).
     */
    required bool   isSecure   = 6;
    /**
     * If true the cookie is only accessible via HTTP.
     */
    required bool   isHTTPOnly = 7;
  }



.. index:: GetCookieSettings

``GetCookieSettings``
---------------------

::

  command GetCookieSettings(Default) returns (CookieSettings) = 4;

Get global settings regarding the allowed number of cookies,
and the max allowed length a cookie.



returns:

.. index:: CookieSettings

.. code-block:: c

  /**
   * The current settings for the cookie manager in the opera host, these settings are read-only and may vary depending on the platform or device used.
   */
  message CookieSettings
  {
    /**
     * The maximum number of cookies the host can store in total.
     * If there is no room for new cookies the host will remove the least recently used cookies to get enough space.
     */
    required uint32 maxCookies          = 1;
    /**
     * The maximum number of cookies allowed in one domain.
     * If there is no room for new cookies the host will remove the least recently used cookies in the domain to get enough space.
     */
    required uint32 maxCookiesPerDomain = 2;
    /**
     * The maxium byte length of a single cookie, if the cookie exceeds this length it will be discarded.
     */
    required uint32 maxCookieLength     = 3;
  }



.. index:: RemoveAllCookies

``RemoveAllCookies``
--------------------

::

  command RemoveAllCookies(Default) returns (Default) = 3;

Removes all cookies.






.. index:: RemoveCookie

``RemoveCookie``
----------------

::

  command RemoveCookie(RemoveCookieArg) returns (Default) = 2;

Removes selected cookies or all cookies in a domain.

@param domain Name of domain to remove cookies from, e.g. "opera.com"
@param path   If specified only removes cookies from specified path or subpath.
@param name   Name of cookie to remove, if unspecified removes all cookies matching domain/path.


argument:

.. index:: RemoveCookieArg

.. code-block:: c

  message RemoveCookieArg
  {
    required string domain = 1;
    optional string path   = 2;
    optional string name   = 3;
  }