1 /* -*- Mode: C; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*- */ 2 /* 3 * GData Client 4 * Copyright (C) Philip Withnall 2008, 2009, 2010, 2014 <philip@tecnocode.co.uk> 5 * 6 * GData Client is free software; you can redistribute it and/or 7 * modify it under the terms of the GNU Lesser General Public 8 * License as published by the Free Software Foundation; either 9 * version 2.1 of the License, or (at your option) any later version. 10 * 11 * GData Client is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 * Lesser General Public License for more details. 15 * 16 * You should have received a copy of the GNU Lesser General Public 17 * License along with GData Client. If not, see <http://www.gnu.org/licenses/>. 18 */ 19 20 #ifndef GDATA_SERVICE_H 21 #define GDATA_SERVICE_H 22 23 #include <glib.h> 24 #include <glib-object.h> 25 #include <libsoup/soup.h> 26 27 #include <gdata/gdata-authorizer.h> 28 #include <gdata/gdata-feed.h> 29 #include <gdata/gdata-query.h> 30 31 G_BEGIN_DECLS 32 33 /** 34 * GDataOperationType: 35 * @GDATA_OPERATION_QUERY: a query 36 * @GDATA_OPERATION_INSERTION: an insertion of a #GDataEntry 37 * @GDATA_OPERATION_UPDATE: an update of a #GDataEntry 38 * @GDATA_OPERATION_DELETION: a deletion of a #GDataEntry 39 * @GDATA_OPERATION_DOWNLOAD: a download of a file 40 * @GDATA_OPERATION_UPLOAD: an upload of a file 41 * @GDATA_OPERATION_AUTHENTICATION: authentication with the service 42 * @GDATA_OPERATION_BATCH: a batch operation with #GDataBatchOperation 43 * 44 * Representations of the different operations performed by the library. 45 * 46 * Since: 0.6.0 47 */ 48 typedef enum { 49 GDATA_OPERATION_QUERY = 1, 50 GDATA_OPERATION_INSERTION, 51 GDATA_OPERATION_UPDATE, 52 GDATA_OPERATION_DELETION, 53 GDATA_OPERATION_DOWNLOAD, 54 GDATA_OPERATION_UPLOAD, 55 GDATA_OPERATION_AUTHENTICATION, 56 GDATA_OPERATION_BATCH 57 } GDataOperationType; 58 59 /** 60 * GDataServiceError: 61 * @GDATA_SERVICE_ERROR_UNAVAILABLE: The service is unavailable due to maintenance or other reasons (e.g. network errors at the server end) 62 * @GDATA_SERVICE_ERROR_PROTOCOL_ERROR: The client or server unexpectedly strayed from the protocol (fatal error) 63 * @GDATA_SERVICE_ERROR_ENTRY_ALREADY_INSERTED: An entry has already been inserted, and cannot be re-inserted 64 * @GDATA_SERVICE_ERROR_AUTHENTICATION_REQUIRED: The user attempted to do something which required authentication, and they weren't authenticated or 65 * didn't have authorization for the operation 66 * @GDATA_SERVICE_ERROR_NOT_FOUND: A requested resource (feed or entry) was not found on the server 67 * @GDATA_SERVICE_ERROR_CONFLICT: There was a conflict when updating an entry on the server; the server-side copy was modified between downloading 68 * and uploading the modified entry 69 * @GDATA_SERVICE_ERROR_FORBIDDEN: Generic error for a forbidden action (not due to having insufficient permissions) 70 * @GDATA_SERVICE_ERROR_BAD_QUERY_PARAMETER: A given query parameter was invalid for the query type 71 * @GDATA_SERVICE_ERROR_NETWORK_ERROR: The service is unavailable due to local network errors (e.g. no Internet connection) 72 * @GDATA_SERVICE_ERROR_PROXY_ERROR: The service is unavailable due to proxy network errors (e.g. proxy unreachable) 73 * @GDATA_SERVICE_ERROR_WITH_BATCH_OPERATION: Generic error when running a batch operation and the whole operation fails 74 * @GDATA_SERVICE_ERROR_API_QUOTA_EXCEEDED: The API request quota for this 75 * developer account has been exceeded for the current time period (e.g. day). 76 * Try again later. (Since: 0.16.0.) 77 * 78 * Error codes for #GDataService operations. 79 */ 80 typedef enum { 81 GDATA_SERVICE_ERROR_UNAVAILABLE = 1, 82 GDATA_SERVICE_ERROR_PROTOCOL_ERROR, 83 GDATA_SERVICE_ERROR_ENTRY_ALREADY_INSERTED, 84 GDATA_SERVICE_ERROR_AUTHENTICATION_REQUIRED, 85 GDATA_SERVICE_ERROR_NOT_FOUND, 86 GDATA_SERVICE_ERROR_CONFLICT, 87 GDATA_SERVICE_ERROR_FORBIDDEN, 88 GDATA_SERVICE_ERROR_BAD_QUERY_PARAMETER, 89 GDATA_SERVICE_ERROR_NETWORK_ERROR, 90 GDATA_SERVICE_ERROR_PROXY_ERROR, 91 GDATA_SERVICE_ERROR_WITH_BATCH_OPERATION, 92 GDATA_SERVICE_ERROR_API_QUOTA_EXCEEDED, 93 } GDataServiceError; 94 95 /** 96 * GDataQueryProgressCallback: 97 * @entry: a new #GDataEntry 98 * @entry_key: the key of the entry (zero-based index of its position in the feed) 99 * @entry_count: the total number of entries in the feed 100 * @user_data: user data passed to the callback 101 * 102 * Callback function called for each #GDataEntry parsed in a #GDataFeed when loading the results of a query. 103 * 104 * It is called in the main thread, so there is no guarantee on the order in which the callbacks are executed, 105 * or whether they will be called in a timely manner. It is, however, guaranteed that they will all be called before 106 * the #GAsyncReadyCallback which signals the completion of the query is called. 107 */ 108 typedef void (*GDataQueryProgressCallback) (GDataEntry *entry, guint entry_key, guint entry_count, gpointer user_data); 109 110 #define GDATA_TYPE_SERVICE (gdata_service_get_type ()) 111 #define GDATA_SERVICE(o) (G_TYPE_CHECK_INSTANCE_CAST ((o), GDATA_TYPE_SERVICE, GDataService)) 112 #define GDATA_SERVICE_CLASS(k) (G_TYPE_CHECK_CLASS_CAST((k), GDATA_TYPE_SERVICE, GDataServiceClass)) 113 #define GDATA_IS_SERVICE(o) (G_TYPE_CHECK_INSTANCE_TYPE ((o), GDATA_TYPE_SERVICE)) 114 #define GDATA_IS_SERVICE_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), GDATA_TYPE_SERVICE)) 115 #define GDATA_SERVICE_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), GDATA_TYPE_SERVICE, GDataServiceClass)) 116 117 #define GDATA_SERVICE_ERROR gdata_service_error_quark () 118 119 typedef struct _GDataServicePrivate GDataServicePrivate; 120 121 /** 122 * GDataService: 123 * 124 * All the fields in the #GDataService structure are private and should never be accessed directly. 125 */ 126 typedef struct { 127 GObject parent; 128 GDataServicePrivate *priv; 129 } GDataService; 130 131 /** 132 * GDataServiceClass: 133 * @parent: the parent class 134 * @api_version: the version of the GData API used by the service (typically <code class="literal">2</code>) 135 * @feed_type: the #GType of the feed class (subclass of #GDataFeed) to use for query results from this service 136 * @append_query_headers: a function to allow subclasses to append their own headers to queries before they are submitted to the online service, 137 * using the given authorization domain; new in version 0.9.0 138 * @parse_error_response: a function to parse error responses to queries from the online service. It should set the error 139 * from the status, reason phrase and response body it is passed. 140 * @get_authorization_domains: a function to return a newly-allocated list of all the #GDataAuthorizationDomains the service makes use of; 141 * while the list should be newly-allocated, the individual domains should not be; not implementing this function is equivalent to returning an 142 * empty list; new in version 0.9.0 143 * @parse_feed: a function to parse feed responses to queries from the online 144 * service; new in version 0.17.0 145 * 146 * The class structure for the #GDataService type. 147 * 148 * Since: 0.9.0 149 */ 150 typedef struct { 151 GObjectClass parent; 152 153 const gchar *api_version; 154 GType feed_type; 155 156 void (*append_query_headers) (GDataService *self, GDataAuthorizationDomain *domain, SoupMessage *message); 157 void (*parse_error_response) (GDataService *self, GDataOperationType operation_type, guint status, const gchar *reason_phrase, 158 const gchar *response_body, gint length, GError **error); 159 GList *(*get_authorization_domains) (void); 160 GDataFeed *(*parse_feed) (GDataService *self, 161 GDataAuthorizationDomain *domain, 162 GDataQuery *query, 163 GType entry_type, 164 SoupMessage *message, 165 GCancellable *cancellable, 166 GDataQueryProgressCallback progress_callback, 167 gpointer progress_user_data, 168 GError **error); 169 170 /*< private >*/ 171 /* Padding for future expansion */ 172 void (*_g_reserved1) (void); 173 void (*_g_reserved2) (void); 174 void (*_g_reserved3) (void); 175 void (*_g_reserved4) (void); 176 void (*_g_reserved5) (void); 177 void (*_g_reserved6) (void); 178 void (*_g_reserved7) (void); 179 } GDataServiceClass; 180 181 G_DEFINE_AUTOPTR_CLEANUP_FUNC (GDataService, g_object_unref) 182 183 GType gdata_service_get_type (void) G_GNUC_CONST; 184 GQuark gdata_service_error_quark (void) G_GNUC_CONST; 185 186 GList *gdata_service_get_authorization_domains (GType service_type) G_GNUC_WARN_UNUSED_RESULT G_GNUC_MALLOC; 187 gboolean gdata_service_is_authorized (GDataService *self); 188 189 GDataAuthorizer *gdata_service_get_authorizer (GDataService *self) G_GNUC_PURE; 190 void gdata_service_set_authorizer (GDataService *self, GDataAuthorizer *authorizer); 191 192 #include <gdata/gdata-query.h> 193 194 GDataFeed *gdata_service_query (GDataService *self, GDataAuthorizationDomain *domain, const gchar *feed_uri, GDataQuery *query, GType entry_type, 195 GCancellable *cancellable, 196 GDataQueryProgressCallback progress_callback, gpointer progress_user_data, 197 GError **error) G_GNUC_WARN_UNUSED_RESULT G_GNUC_MALLOC; 198 void gdata_service_query_async (GDataService *self, GDataAuthorizationDomain *domain, const gchar *feed_uri, GDataQuery *query, GType entry_type, 199 GCancellable *cancellable, 200 GDataQueryProgressCallback progress_callback, gpointer progress_user_data, GDestroyNotify destroy_progress_user_data, 201 GAsyncReadyCallback callback, gpointer user_data); 202 GDataFeed *gdata_service_query_finish (GDataService *self, GAsyncResult *async_result, GError **error) G_GNUC_WARN_UNUSED_RESULT G_GNUC_MALLOC; 203 204 GDataEntry *gdata_service_query_single_entry (GDataService *self, GDataAuthorizationDomain *domain, const gchar *entry_id, GDataQuery *query, 205 GType entry_type, GCancellable *cancellable, GError **error) G_GNUC_WARN_UNUSED_RESULT G_GNUC_MALLOC; 206 void gdata_service_query_single_entry_async (GDataService *self, GDataAuthorizationDomain *domain, const gchar *entry_id, GDataQuery *query, 207 GType entry_type, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data); 208 GDataEntry *gdata_service_query_single_entry_finish (GDataService *self, GAsyncResult *async_result, 209 GError **error) G_GNUC_WARN_UNUSED_RESULT G_GNUC_MALLOC; 210 211 GDataEntry *gdata_service_insert_entry (GDataService *self, GDataAuthorizationDomain *domain, const gchar *upload_uri, GDataEntry *entry, 212 GCancellable *cancellable, GError **error) G_GNUC_WARN_UNUSED_RESULT G_GNUC_MALLOC; 213 void gdata_service_insert_entry_async (GDataService *self, GDataAuthorizationDomain *domain, const gchar *upload_uri, GDataEntry *entry, 214 GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data); 215 GDataEntry *gdata_service_insert_entry_finish (GDataService *self, GAsyncResult *async_result, 216 GError **error) G_GNUC_WARN_UNUSED_RESULT G_GNUC_MALLOC; 217 218 GDataEntry *gdata_service_update_entry (GDataService *self, GDataAuthorizationDomain *domain, GDataEntry *entry, 219 GCancellable *cancellable, GError **error) G_GNUC_WARN_UNUSED_RESULT G_GNUC_MALLOC; 220 void gdata_service_update_entry_async (GDataService *self, GDataAuthorizationDomain *domain, GDataEntry *entry, GCancellable *cancellable, 221 GAsyncReadyCallback callback, gpointer user_data); 222 GDataEntry *gdata_service_update_entry_finish (GDataService *self, GAsyncResult *async_result, 223 GError **error) G_GNUC_WARN_UNUSED_RESULT G_GNUC_MALLOC; 224 225 gboolean gdata_service_delete_entry (GDataService *self, GDataAuthorizationDomain *domain, GDataEntry *entry, 226 GCancellable *cancellable, GError **error); 227 void gdata_service_delete_entry_async (GDataService *self, GDataAuthorizationDomain *domain, GDataEntry *entry, GCancellable *cancellable, 228 GAsyncReadyCallback callback, gpointer user_data); 229 gboolean gdata_service_delete_entry_finish (GDataService *self, GAsyncResult *async_result, GError **error); 230 231 #ifndef LIBGDATA_DISABLE_DEPRECATED 232 SoupURI *gdata_service_get_proxy_uri (GDataService *self) G_GNUC_PURE G_GNUC_DEPRECATED_FOR (gdata_service_get_proxy_resolver); 233 void gdata_service_set_proxy_uri (GDataService *self, SoupURI *proxy_uri) G_GNUC_DEPRECATED_FOR (gdata_service_set_proxy_resolver); 234 #endif /* !LIBGDATA_DISABLE_DEPRECATED */ 235 236 GProxyResolver *gdata_service_get_proxy_resolver (GDataService *self) G_GNUC_PURE; 237 void gdata_service_set_proxy_resolver (GDataService *self, GProxyResolver *proxy_resolver); 238 239 guint gdata_service_get_timeout (GDataService *self) G_GNUC_PURE; 240 void gdata_service_set_timeout (GDataService *self, guint timeout); 241 242 const gchar *gdata_service_get_locale (GDataService *self) G_GNUC_PURE; 243 void gdata_service_set_locale (GDataService *self, const gchar *locale); 244 245 G_END_DECLS 246 247 #endif /* !GDATA_SERVICE_H */ 248