## GDataCommentable GDataCommentable — GData commentable interface |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    #include <gdata/gdata-commentable.h>

                        GDataCommentable;
                        GDataCommentableInterface;
    GDataFeed *         gdata_commentable_query_comments    (GDataCommentable *self,
                                                             GDataService *service,
                                                             GDataQuery *query,
                                                             GCancellable *cancellable,
                                                             GDataQueryProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             GError **error);
    void                gdata_commentable_query_comments_async
                                                            (GDataCommentable *self,
                                                             GDataService *service,
                                                             GDataQuery *query,
                                                             GCancellable *cancellable,
                                                             GDataQueryProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             GDestroyNotify destroy_progress_user_data,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GDataFeed *         gdata_commentable_query_comments_finish
                                                            (GDataCommentable *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    GDataComment *      gdata_commentable_insert_comment    (GDataCommentable *self,
                                                             GDataService *service,
                                                             GDataComment *comment_,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                gdata_commentable_insert_comment_async
                                                            (GDataCommentable *self,
                                                             GDataService *service,
                                                             GDataComment *comment_,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GDataComment *      gdata_commentable_insert_comment_finish
                                                            (GDataCommentable *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    gboolean            gdata_commentable_delete_comment    (GDataCommentable *self,
                                                             GDataService *service,
                                                             GDataComment *comment_,
                                                             GCancellable *cancellable,
                                                             GError **error);
    void                gdata_commentable_delete_comment_async
                                                            (GDataCommentable *self,
                                                             GDataService *service,
                                                             GDataComment *comment_,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            gdata_commentable_delete_comment_finish
                                                            (GDataCommentable *self,
                                                             GAsyncResult *result,
                                                             GError **error);

## Object Hierarchy

      GInterface
       +----GDataCommentable

## Prerequisites

GDataCommentable requires GDataEntry.

## Known Implementations

GDataCommentable is implemented by GDataPicasaWebFile and GDataYouTubeVideo.

## Description

GDataCommentable is an interface which can be implemented by commentable objects: objects which support having comments added to them by users, such as videos and photos.

Comments may be queried, added and deleted. Note that they may not be edited.

GDataCommentable objects may not support all operations on comments, on an instance-by-instance basis (i.e. it's an invalid assumption that if, for example, one GDataYouTubeVideo doesn't support adding comments all other GDataYouTubeVideos don't support adding comments either). Specific documentation for a particular type of GDataCommentable may state otherwise, though.

Example 6. Querying for Comments

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    GDataService *service;
    GDataCommentable *commentable;

    /* Create a service */
    service = create_service ();

    /* Retrieve the GDataCommentable which is going to be queried. This may be, for example, a GDataYouTubeVideo. */
    commentable = get_commentable ();

    /* Start the async. query for the comments. */
    gdata_commentable_query_comments_async (commentable, service, NULL, NULL, NULL, NULL, NULL, (GAsyncReadyCallback) query_comments_cb, NULL);

    g_object_unref (service);
    g_object_unref (commentable);

    static void
    query_comments_cb (GDataCommentable *commentable, GAsyncResult *result, gpointer user_data)
    {
        GDataFeed *comment_feed;
        GList *comments, *i;
        GError *error = NULL;

        comment_feed = gdata_commentable_query_comments_finish (commentable, result, &error);

        if (error != NULL) {
            /* Error! */
            g_error ("Error querying comments: %s", error->message);
            g_error_free (error);
            return;
        }

        /* Examine the comments. */
        comments = gdata_feed_get_entries (comment_feed);
        for (i = comments; i != NULL; i = i->next) {
            /* Note that this will actually be a subclass of GDataComment,
             * such as GDataYouTubeComment or GDataPicasaWebComment. */
            GDataComment *comment = GDATA_COMMENT (i->data);
            GDataAuthor *author;

            /* Note that in practice it might not always be safe to assume that a comment always has an author. */
            author = GDATA_AUTHOR (gdata_entry_get_authors (GDATA_ENTRY (comment))->data);

            g_message ("Comment by %s (%s): %s",
                       gdata_author_get_name (author),
                       gdata_author_get_uri (author),
                       gdata_entry_get_content (GDATA_ENTRY (comment)));
        }

        g_object_unref (comment_feed);
    }

## Details

### GDataCommentable

    typedef struct _GDataCommentable GDataCommentable;

All the fields in the GDataCommentable structure are private and should never be accessed directly

Since 0.10.0

### GDataCommentableInterface

    typedef struct {
    	GTypeInterface parent;

    	GType comment_type;

    	GDataAuthorizationDomain *(*get_authorization_domain) (GDataCommentable *self);

    	gchar *(*get_query_comments_uri) (GDataCommentable *self);
    	gchar *(*get_insert_comment_uri) (GDataCommentable *self, GDataComment *comment);
    	gboolean (*is_comment_deletable) (GDataCommentable *self, GDataComment *comment);
    } GDataCommentableInterface;

The interface structure for the GDataCommentable interface.

GTypeInterface `parent`; | the parent type
GType `comment_type`; | the GType of the comment class (subclass of GDataComment) to use for query results from this commentable object
`get_authorization_domain` () | a function to return the GDataAuthorizationDomain to be used for all operations on the comments belonging to this commentable object; not implementing this function is equivalent to returning `NULL` from it, which signifies that operations on the comments don't require authorization. [allow-none]
`get_query_comments_uri` () | a function that returns the URI of a GDataFeed of comments from a commentable object, or `NULL` if the given commentable object doesn't support commenting; free with `g_free()`
`get_insert_comment_uri` () | a function that returns the URI to add new comments to the commentable object, or `NULL` if the given commentable object doesn't support adding comments; free with `g_free()`
`is_comment_deletable` () | a function that returns `TRUE` if the given comment may be deleted, `FALSE` otherwise

Since 0.10.0

### gdata_commentable_query_comments ()

    GDataFeed *         gdata_commentable_query_comments    (GDataCommentable *self,
                                                             GDataService *service,
                                                             GDataQuery *query,
                                                             GCancellable *cancellable,
                                                             GDataQueryProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             GError **error);

Retrieves a GDataFeed containing the GDataComments representing the comments on the GDataCommentable which match the given `query`.

If the GDataCommentable doesn't support commenting, `NULL` will be returned and `error` will be set to `GDATA_SERVICE_ERROR_FORBIDDEN`. This is in contrast to if it does support commenting but hasn't had any comments added yet, in which case an empty GDataFeed will be returned and no error will be set.

`self` : | a GDataCommentable
`service` : | a GDataService representing the service with which the object's comments will be manipulated
`query` : | a GDataQuery with query parameters, or `NULL`. [allow-none]
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`progress_callback` : | a GDataQueryProgressCallback to call when a comment is loaded, or `NULL`. [allow-none][scope call][closure progress_user_data]
`progress_user_data` : | data to pass to the `progress_callback` function. [closure]
`error` : | a GError, or `NULL`
Returns : | a GDataFeed of GDataComments, or `NULL`; unref with `g_object_unref()`. [transfer full][allow-none]

Since 0.10.0

### gdata_commentable_query_comments_async ()

    void                gdata_commentable_query_comments_async
                                                            (GDataCommentable *self,
                                                             GDataService *service,
                                                             GDataQuery *query,
                                                             GCancellable *cancellable,
                                                             GDataQueryProgressCallback progress_callback,
                                                             gpointer progress_user_data,
                                                             GDestroyNotify destroy_progress_user_data,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Retrieves a GDataFeed containing the GDataComments representing the comments on the GDataCommentable which match the given `query`. `self`, `service` and `query` are all reffed when this method is called, so can safely be freed after this method returns.

For more details, see `gdata_commentable_query_comments()`, which is the synchronous version of this method.

When the operation is finished, `callback` will be called. You can then call `gdata_commentable_query_comments_finish()` to get the results of the operation.

`self` : | a GDataCommentable
`service` : | a GDataService representing the service with which the object's comments will be manipulated
`query` : | a GDataQuery with query parameters, or `NULL`. [allow-none]
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`progress_callback` : | a GDataQueryProgressCallback to call when a comment is loaded, or `NULL`. [allow-none][scope notified][closure progress_user_data]
`progress_user_data` : | data to pass to the `progress_callback` function. [closure]
`destroy_progress_user_data` : | a function to call when `progress_callback` will not be called any more, or `NULL`; this function will be called with `progress_user_data` as a parameter and can be used to free any memory allocated for it. [allow-none]
`callback` : | a GAsyncReadyCallback to call when the query is finished
`user_data` : | data to pass to the `callback` function. [closure]

Since 0.10.0

### gdata_commentable_query_comments_finish ()

    GDataFeed *         gdata_commentable_query_comments_finish
                                                            (GDataCommentable *self,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes an asynchronous comment query operation started with `gdata_commentable_query_comments_async()`.

`self` : | a GDataCommentable
`result` : | a GAsyncResult
`error` : | a GError, or `NULL`
Returns : | a GDataFeed of GDataComments, or `NULL`; unref with `g_object_unref()`. [transfer full][allow-none]

Since 0.10.0

### gdata_commentable_insert_comment ()

    GDataComment *      gdata_commentable_insert_comment    (GDataCommentable *self,
                                                             GDataService *service,
                                                             GDataComment *comment_,
                                                             GCancellable *cancellable,
                                                             GError **error);

Adds `comment` to the GDataCommentable.

If the GDataCommentable doesn't support commenting, `NULL` will be returned and `error` will be set to `GDATA_SERVICE_ERROR_FORBIDDEN`.

`self` : | a GDataCommentable
`service` : | a GDataService with which the comment will be added
`comment_` : | a new comment to be added to the GDataCommentable
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`error` : | a GError, or `NULL`
Returns : | the added GDataComment, or `NULL`; unref with `g_object_unref()`. [transfer full][allow-none]

Since 0.10.0

### gdata_commentable_insert_comment_async ()

    void                gdata_commentable_insert_comment_async
                                                            (GDataCommentable *self,
                                                             GDataService *service,
                                                             GDataComment *comment_,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Adds `comment` to the GDataCommentable. `self`, `service` and `comment_` are all reffed when this method is called, so can safely be freed after this method returns.

For more details, see `gdata_commentable_insert_comment()`, which is the synchronous version of this method.

When the operation is finished, `callback` will be called. You can then call `gdata_commentable_insert_comment_finish()` to get the results of the operation.

`self` : | a GDataCommentable
`service` : | a GDataService with which the comment will be added
`comment_` : | a new comment to be added to the GDataCommentable
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`callback` : | a GAsyncReadyCallback to call when the operation is finished
`user_data` : | data to pass to the `callback` function. [closure]

Since 0.10.0

### gdata_commentable_insert_comment_finish ()

    GDataComment *      gdata_commentable_insert_comment_finish
                                                            (GDataCommentable *self,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes an asynchronous comment insertion operation started with `gdata_commentable_insert_comment_async()`.

`self` : | a GDataCommentable
`result` : | a GAsyncResult
`error` : | a GError, or `NULL`
Returns : | the added GDataComment, or `NULL`; unref with `g_object_unref()`. [transfer full][allow-none]

Since 0.10.0

### gdata_commentable_delete_comment ()

    gboolean            gdata_commentable_delete_comment    (GDataCommentable *self,
                                                             GDataService *service,
                                                             GDataComment *comment_,
                                                             GCancellable *cancellable,
                                                             GError **error);

Deletes `comment` from the GDataCommentable.

If the given `comment` isn't deletable (either because the service doesn't support deleting comments at all, or because this particular comment is not deletable due to having insufficient permissions), `GDATA_SERVICE_ERROR_FORBIDDEN` will be set in `error` and `FALSE` will be returned.

`self` : | a GDataCommentable
`service` : | a GDataService with which the comment will be deleted
`comment_` : | a comment to be deleted
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`error` : | a GError, or `NULL`
Returns : | `TRUE` if the comment was successfully deleted, `FALSE` otherwise

Since 0.10.0

### gdata_commentable_delete_comment_async ()

    void                gdata_commentable_delete_comment_async
                                                            (GDataCommentable *self,
                                                             GDataService *service,
                                                             GDataComment *comment_,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Deletes `comment` from the GDataCommentable. `self`, `service` and `comment_` are all reffed when this method is called, so can safely be freed after this method returns.

For more details, see `gdata_commentable_delete_comment()`, which is the synchronous version of this method.

When the operation is finished, `callback` will be called. You can then call `gdata_commentable_delete_comment_finish()` to get the results of the operation.

`self` : | a GDataCommentable
`service` : | a GDataService with which the comment will be deleted
`comment_` : | a comment to be deleted
`cancellable` : | optional GCancellable object, or `NULL`. [allow-none]
`callback` : | a GAsyncReadyCallback to call when the operation is finished
`user_data` : | data to pass to the `callback` function. [closure]

Since 0.10.0

### gdata_commentable_delete_comment_finish ()

    gboolean            gdata_commentable_delete_comment_finish
                                                            (GDataCommentable *self,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes an asynchronous comment deletion operation started with `gdata_commentable_delete_comment_async()`.

`self` : | a GDataCommentable
`result` : | a GAsyncResult
`error` : | a GError, or `NULL`
Returns : | `TRUE` if the comment was successfully deleted, `FALSE` otherwise

Since 0.10.0