|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
<html>
|
|
Packit |
4b6dd7 |
<head>
|
|
Packit |
4b6dd7 |
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
|
Packit |
4b6dd7 |
<title>GData Overview: GData Reference Manual</title>
|
|
Packit |
4b6dd7 |
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
|
|
Packit |
4b6dd7 |
<link rel="home" href="index.html" title="GData Reference Manual">
|
|
Packit |
4b6dd7 |
<link rel="up" href="pt01.html" title="Part I. GData Overview">
|
|
Packit |
4b6dd7 |
<link rel="prev" href="pt01.html" title="Part I. GData Overview">
|
|
Packit |
4b6dd7 |
<link rel="next" href="gdata-running.html" title="Running GData Applications">
|
|
Packit |
4b6dd7 |
<meta name="generator" content="GTK-Doc V1.26.1 (XML mode)">
|
|
Packit |
4b6dd7 |
<link rel="stylesheet" href="style.css" type="text/css">
|
|
Packit |
4b6dd7 |
</head>
|
|
Packit |
4b6dd7 |
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
GData Overview
|
|
Packit |
4b6dd7 |
GData Overview — overview of libgdata's architecture
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
Introduction
|
|
Packit |
4b6dd7 |
libgdata is a library to allow access to web services using the GData protocol from the desktop. The GData protocol is a simple protocol for reading and writing
|
|
Packit |
4b6dd7 |
data on the web, designed by Google.
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
Protocols
|
|
Packit |
4b6dd7 |
Google's services were originally only accessible using an XML-based protocol called GData. However, later additions
|
|
Packit |
4b6dd7 |
to the set of available services use a REST-style JSON protocol. libgdata supports both protocols, although specific
|
|
Packit |
4b6dd7 |
services use exactly one of the two protocols.
|
|
Packit |
4b6dd7 |
The core API in libgdata transparently supports both protocols, so client code need not consider which protocol to use.
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
XML protocol
|
|
Packit |
4b6dd7 |
The GData XML protocol is designed by Google to allow interaction with their web services. It is based on the Atom Publishing
|
|
Packit |
4b6dd7 |
protocol, with namespaced XML additions. Communication between the client and server is broadly achieved through HTTP
|
|
Packit |
4b6dd7 |
requests with query parameters, and Atom feeds being returned with result entries. Each service
|
|
Packit |
4b6dd7 |
has its own namespaced additions to the GData protocol; for example, the Google Calendar service's API has
|
|
Packit |
4b6dd7 |
specialisations for addresses and time periods.
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
Figure 1.
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
An overview of the data flow when making a request of a GData service.
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
Results are always returned in the form of result feeds, containing multiple
|
|
Packit |
4b6dd7 |
entries. How the entries are interpreted depends on what was queried of the service, but when
|
|
Packit |
4b6dd7 |
using libgdata, this is all taken care of transparently.
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
JSON protocol
|
|
Packit |
4b6dd7 |
The more recent JSON protocol is similar in architecture to the XML protocol: entries are arranged into feeds, and the core
|
|
Packit |
4b6dd7 |
operations available are: listing all entries, getting a specific entry, inserting an entry, updating an entry and deleting an entry.
|
|
Packit |
4b6dd7 |
The key difference between the two protocols, apart from the serialisation format, is that the JSON protocol is not namespaced. Each
|
|
Packit |
4b6dd7 |
service uses a specific JSON format, and there is no formal sharing of data structures between services. For example, every entry
|
|
Packit |
4b6dd7 |
in the XML protocol is required to have a title, ID and update time (as per the Atom specification). Such commonality between
|
|
Packit |
4b6dd7 |
JSON entries is purely ad-hoc.
|
|
Packit |
4b6dd7 |
Differences between the XML and JSON protocols are hidden by the libgdata API. Both protocols are implemented by the standard
|
|
Packit |
4b6dd7 |
GDataService, GDataFeed and
|
|
Packit |
4b6dd7 |
GDataEntry classes.
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
Structure
|
|
Packit |
4b6dd7 |
The basic design of libgdata mirrors the protocol's structure quite closely:
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
Figure 2.
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
An overview of the libgdata class structure.
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
GDataService
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
Subclassed for each different web service implemented, this class represents a single client's
|
|
Packit |
4b6dd7 |
connection to the relevant web service, holding their authentication state, and making the necessary
|
|
Packit |
4b6dd7 |
requests to read and write data to and from the service. All top-level actions, such as creating a new
|
|
Packit |
4b6dd7 |
object on the server, are carried out through a service.
|
|
Packit |
4b6dd7 |
There should be one GDataService subclass for
|
|
Packit |
4b6dd7 |
each of the services listed in the GData
|
|
Packit |
4b6dd7 |
documentation.
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
GDataQuery
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
For queries to have multiple individual parameters, a
|
|
Packit |
4b6dd7 |
GDataQuery can be used to specify the parameters.
|
|
Packit |
4b6dd7 |
Query objects are optional, and can only be used with queries (not with entry insertions, updates
|
|
Packit |
4b6dd7 |
or deletions). The query object builds the query URI used by the
|
|
Packit |
4b6dd7 |
GDataService when sending the query to the
|
|
Packit |
4b6dd7 |
server.
|
|
Packit |
4b6dd7 |
Services can subclass GDataQuery if the service
|
|
Packit |
4b6dd7 |
supports non-standard query parameters.
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
GDataFeed
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
Effectively a list of GDataEntrys, the
|
|
Packit |
4b6dd7 |
GDataFeed class is a direct counterpart of the root
|
|
Packit |
4b6dd7 |
<feed> element in the Atom feeds which form the GData protocol. It contains the
|
|
Packit |
4b6dd7 |
elements in a query response, as well as general information about the response, such as links to
|
|
Packit |
4b6dd7 |
related feeds and the categories under which the query response falls.
|
|
Packit |
4b6dd7 |
GDataFeed is usually not subclassed by services,
|
|
Packit |
4b6dd7 |
as there are rarely service-specific elements in a feed itself.
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
GDataEntry
|
|
Packit |
4b6dd7 |
A GDataEntry is a direct counterpart of the
|
|
Packit |
4b6dd7 |
<entry> element in the Atom feeds which form the GData protocol. It represents a
|
|
Packit |
4b6dd7 |
single object of unspecified semantics; an entry could be anything from a calendar event to a video
|
|
Packit |
4b6dd7 |
comment or access control rule. Semantics are given to entries by subclassing
|
|
Packit |
4b6dd7 |
GDataEntry for the various types of entries returned
|
|
Packit |
4b6dd7 |
by queries to a service. Such subclasses implement useful, relevant and query-specific properties
|
|
Packit |
4b6dd7 |
on the entry (such as the duration of a video, or the recurrence rules of a calendar event).
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
Development Philosophy
|
|
Packit |
4b6dd7 |
As the GData protocol (and all the service-specific protocols which extend it) is reasonably young, it is subject to fairly
|
|
Packit |
4b6dd7 |
frequent updates and expansions. While backwards compatibility is maintained, these updates necessitate that libgdata
|
|
Packit |
4b6dd7 |
remains fairly flexible in how it treats data. The sections below detail some of the ways in which libgdata achieves this,
|
|
Packit |
4b6dd7 |
and the reasoning behind them, as well as other major design decisions behind libgdata's API.
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
Enumerable Properties
|
|
Packit |
4b6dd7 |
There are many class properties in libgdata which should, at first glance, be implemented as enumerated types. Function
|
|
Packit |
4b6dd7 |
calls such as gdata_link_get_relation_type()
|
|
Packit |
4b6dd7 |
and gdata_gd_im_address_get_protocol()
|
|
Packit |
4b6dd7 |
would, in a conventional library, return a value from an enum, which would work well, and be more typesafe and
|
|
Packit |
4b6dd7 |
memory-efficient than using arbitrary strings.
|
|
Packit |
4b6dd7 |
However, such an implementation would not be forwards-compatible. If a protocol addition was made which added another
|
|
Packit |
4b6dd7 |
link relation type, or added supportf or another IM protocol, there would be no way for libgdata to represent some
|
|
Packit |
4b6dd7 |
of the data it retrieved from the server. It could return an “other” value from the enum, but that could lead to
|
|
Packit |
4b6dd7 |
data loss in the common case of GData entries being queried from the server, processed, then updated again.
|
|
Packit |
4b6dd7 |
For this reason – which is made more troublesome by the fact that it is unpredictable when updates to the protocol are
|
|
Packit |
4b6dd7 |
released, or when updated XML/JSON will start coming over the wire – libgdata uses enumerated types sparingly; they are
|
|
Packit |
4b6dd7 |
only used when it is very improbable (or even impossible) for the property in question to be extended or changed in
|
|
Packit |
4b6dd7 |
the future. In any other case, a string value is used instead, with libgdata providing #defined values
|
|
Packit |
4b6dd7 |
for the known values of the property. These values should be used as much as possible by applications which use
|
|
Packit |
4b6dd7 |
libgdata (i.e. they should be treated as if they were enumerated values), but applications are free to use strings
|
|
Packit |
4b6dd7 |
of their own, too. All validation of such pseudo-enums is left to the server.
|
|
Packit |
4b6dd7 |
One situation where it is acceptable to use enumerated types is in API which is only ever used to query the server, and
|
|
Packit |
4b6dd7 |
isn't involved in processing or representing the response at all, i.e. subclasses of
|
|
Packit |
4b6dd7 |
GDataQuery.
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
String Constants
|
|
Packit |
4b6dd7 |
As the protocols are XML- or JSON-based, they make extensive use of string constants, typically as
|
|
Packit |
4b6dd7 |
enumerated types or namespaced URIs. To stop the authors of applications
|
|
Packit |
4b6dd7 |
which use libgdata from having to continually look up the correct “magic strings” to use, all such strings should
|
|
Packit |
4b6dd7 |
be #defined in libgdata, and referenced in the appropriate function documentation.
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
New Services
|
|
Packit |
4b6dd7 |
The API required to implement support for a new service using libgdata is not publicly exposed. This is because doing
|
|
Packit |
4b6dd7 |
so would clutter the API to a large extent; for example, exposing various properties as writeable which are currently
|
|
Packit |
4b6dd7 |
only readable. While the freedom for users of libgdata to write their own services is a good one, it is outweighed by
|
|
Packit |
4b6dd7 |
the muddlement that this would bring to the API.
|
|
Packit |
4b6dd7 |
Furthermore, since it is highly unlikely that anyone except Google will use GData as a basis for communicating with
|
|
Packit |
4b6dd7 |
their service, there is little harm in restricting the implementation of services to libgdata. If someone wants to
|
|
Packit |
4b6dd7 |
implement support for a new GData service, it is for the benefit of everyone if this implementation is done in libgdata
|
|
Packit |
4b6dd7 |
itself, rather than their application.
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
Cancellable Support
|
|
Packit |
4b6dd7 |
As libgdata is a network library, it has to be able to deal with operations which take a long (and indeterminate) amount
|
|
Packit |
4b6dd7 |
of time due to network latencies. As well as providing asynchronous operation support, every such operation in libgdata
|
|
Packit |
4b6dd7 |
is cancellable, using GCancellable.
|
|
Packit |
4b6dd7 |
Using GCancellable, any ongoing libgdata operation can be cancelled
|
|
Packit |
4b6dd7 |
from any other thread by calling g_cancellable_cancel.
|
|
Packit |
4b6dd7 |
If the ongoing operation is doing network activity, the operation will be cancelled as safely as possible (although
|
|
Packit |
4b6dd7 |
the server's state cannot be guaranteed when cancelling a non-idempotent operation, such as an insertion or update,
|
|
Packit |
4b6dd7 |
since the server may have already committed the results of the operation, but might not have returned them to libgdata
|
|
Packit |
4b6dd7 |
yet) and the operation will return to its calling function with a
|
|
Packit |
4b6dd7 |
G_IO_ERROR_CANCELLED error. Similarly,
|
|
Packit |
4b6dd7 |
if the operation is yet to do network activity, it will return with the above error before the network activity is
|
|
Packit |
4b6dd7 |
started, leaving the server unchanged.
|
|
Packit |
4b6dd7 |
However, if the operation has finished its network activity, libgdata does not guarantee that it will return with an
|
|
Packit |
4b6dd7 |
error — it may return successfully. There is no way to fix this, as it is an inherent race condition between checking
|
|
Packit |
4b6dd7 |
for cancellation for the last time, and returning the successful result. Rather than reduce the probability of the race
|
|
Packit |
4b6dd7 |
condition occurring, but still have the possibility of it occurring, libgdata will just continue to process an operation
|
|
Packit |
4b6dd7 |
after its network activity is over, and return success.
|
|
Packit |
4b6dd7 |
This may be useful in situations where the user is cancelling an operation due to it taking too long; the application
|
|
Packit |
4b6dd7 |
using libgdata may want to make use of the result of the operation, even if it has previously tried to cancel the
|
|
Packit |
4b6dd7 |
operation after network activity finished.
|
|
Packit |
4b6dd7 |
The behaviour of cancellation in libgdata can be represented as follows:
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
Figure 3.
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
The behaviour of cancellation in libgdata.
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
Privacy
|
|
Packit |
4b6dd7 |
Privacy is an important consideration with code such as libgdata's, which handles valuable data such as people's
|
|
Packit |
4b6dd7 |
address books and Google Account login details.
|
|
Packit |
4b6dd7 |
Unfortunately, it's infeasible for libgdata to ensure that no private data is ever leaked from a process. To do this
|
|
Packit |
4b6dd7 |
properly would require almost all the data allocated by libgdata (and all the libraries it depends on, all the way down
|
|
Packit |
4b6dd7 |
to the TLS implementation) to use non-pageable memory for all network requests and responses, and to be careful about
|
|
Packit |
4b6dd7 |
zeroing them before freeing them. There isn't enough support for this level of paranoia in the lower levels of the
|
|
Packit |
4b6dd7 |
stack (such as libsoup).
|
|
Packit |
4b6dd7 |
However, it is feasible to ensure that the user's password and authentication/authorization tokens aren't leaked. This
|
|
Packit |
4b6dd7 |
is done in several ways in libgdata:
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
If libgdata is compiled with libgcr support enabled (using the
|
|
Packit |
4b6dd7 |
--enable-gnome configuration flag), it will use libgcr's support for
|
|
Packit |
4b6dd7 |
non-pageable memory. This will try hard to avoid passwords and auth. tokens being paged out to disk at
|
|
Packit |
4b6dd7 |
any point (although there are circumstances, such as when hibernating, where this is
|
|
Packit |
4b6dd7 |
unavoidable).
|
|
Packit |
4b6dd7 |
Otherwise, libgdata will ensure that passwords and auth. tokens are zeroed out in memory before being
|
|
Packit |
4b6dd7 |
freed, which lowers the chance of them reaching disk at a later stage.
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
Unless run with LIBGDATA_DEBUG set to 4, libgdata will attempt to
|
|
Packit |
4b6dd7 |
redact all usernames, passwords and auth. tokens from debug log output. This aims to prevent accidental
|
|
Packit |
4b6dd7 |
disclosure of passwords, etc. in bug reports. Currently, this is implemented using a fixed set of
|
|
Packit |
4b6dd7 |
search patterns, so it's possible that certain bits of private information will not be redacted; any
|
|
Packit |
4b6dd7 |
such occurrence is a bug which should be reported on
|
|
Packit |
4b6dd7 |
GNOME
|
|
Packit |
4b6dd7 |
Bugzilla.
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
libgdata universally uses HTTPS rather than HTTP for communicating with servers. The port which is used may be changed
|
|
Packit |
4b6dd7 |
for testing purposes, using the LIBGDATA_HTTPS_PORT environment variable; but the protocol used will
|
|
Packit |
4b6dd7 |
always be HTTPS.
|
|
Packit |
4b6dd7 |
libgdata provides ways to upload and download files, but does not implement code for loading or saving those files to
|
|
Packit |
4b6dd7 |
or from disk. Since these files will typically be user data (such as their Google Drive documents), it is highly
|
|
Packit |
4b6dd7 |
recommended that they are given restricted permissions, any temporary files are only readable by the current user,
|
|
Packit |
4b6dd7 |
and files are potentially encrypted on disk where appropriate. The aim is to avoid leaking user data to other users
|
|
Packit |
4b6dd7 |
of the system, or to attackers who gain access to the user’s hard drive (which may not be encrypted). libgdata itself
|
|
Packit |
4b6dd7 |
only guarantees that data is encrypted while being sent over the network.
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
|
|
Packit |
4b6dd7 |
Generated by GTK-Doc V1.26.1
|
|
Packit |
4b6dd7 |
</body>
|
|
Packit |
4b6dd7 |
</html>
|
