Bug 29456

I guess the "fire and forget" API should be something like that:

void tp_account_channel_request_create_channel_async (
    TpAccountChannelRequest *self,
    GCancellable *cancellable,
    GAsyncReadyCallback callback,
    gpointer user_data);

gboolean tp_account_channel_request_create_channel_finish (
    TpAccountChannelRequest *self,
    GAsyncResult *result,
    GError **error);

+ the _ensure_ equivalents.

The operation succeed once the ChannelRequest fired the Suceeded or Failed signal.


The "fire and observe" case could be something like:

void tp_account_channel_request_create_and_observe_channel_async (
    TpAccountChannelRequest *self,
    GCancellable *cancellable,
    GAsyncReadyCallback callback,
    gpointer user_data);

TpChannel * tp_account_channel_request_create_and_observe_channel_finish (
    TpAccountChannelRequest *self,
    GAsyncResult *result,
    TpHandleChannelsContext **context,
    GError **error) G_GNUC_WARN_UNUSED_RESULT;

(In reply to comment #1)
> I guess the "fire and forget" API should be something like
> [...]
> The operation succeed once the ChannelRequest fired the Suceeded or Failed
> signal.

Exactly.

> The "fire and observe" case could be something like:
[...]
>     TpHandleChannelsContext **context,

You wouldn't get this return value, but otherwise, yes. This is Bug #29457.

(In reply to comment #1)

> void tp_account_channel_request_create_channel_async (
>     TpAccountChannelRequest *self,
>     GCancellable *cancellable,
>     GAsyncReadyCallback callback,
>     gpointer user_data);

Actually it should be:

void tp_account_channel_request_create_channel_async (
    TpAccountChannelRequest *self,
    const gchar *preferred_handler,
    GCancellable *cancellable,
    GAsyncReadyCallback callback,
    gpointer user_data);

Looks pretty good; some minor nitpicking, mostly for the docs.

> +  gboolean handle;

At a glance this looks like it ought to be a TpHandle, not an imperative verb. Perhaps should_handle?

> +    DEBUG ("Proceed succeeded; waiting the Succeeded signal");

"waiting for the Succeeded signal", or "awaiting the Succeeded signal" (either is valid)

> + * When the channel has been created and dispatched, @callback will be called.

This sounds as though it always succeeds; perhaps "@callback will be called when the channel has been created and dispatched, or the request has failed"?

> + * When the channel has been ensure and dispatched (or re-dispatched if the
> + * channel already exists), @callback will be called.

s/ensure/ensured/, but actually I'd say:

"@callback will be called when an existing channel's handler has been notified, a new channel has been created and dispatched, or the request has failed"

> + * Returns: %TRUE if the channel was successfully ensure and (re-)dispatched,
> + * otherwise %NULL.

s/ensure/ensured/, s/NULL/FALSE/ (the create variant also says NULL)

(In reply to comment #4)
> Looks pretty good; some minor nitpicking, mostly for the docs.

I renamed and rebased the branch:
http://git.collabora.co.uk/?p=user/cassidy/telepathy-glib;a=shortlog;h=refs/heads/request-forget-29456

> > +  gboolean handle;
> 
> At a glance this looks like it ought to be a TpHandle, not an imperative verb.
> Perhaps should_handle?

renamed.

> > +    DEBUG ("Proceed succeeded; waiting the Succeeded signal");
> 
> "waiting for the Succeeded signal", or "awaiting the Succeeded signal" (either
> is valid)

fixed.

> > + * When the channel has been created and dispatched, @callback will be called.
> 
> This sounds as though it always succeeds; perhaps "@callback will be called
> when the channel has been created and dispatched, or the request has failed"?

changed.

> > + * When the channel has been ensure and dispatched (or re-dispatched if the
> > + * channel already exists), @callback will be called.
> 
> s/ensure/ensured/, but actually I'd say:
> 
> "@callback will be called when an existing channel's handler has been notified,
> a new channel has been created and dispatched, or the request has failed"

changed.

> > + * Returns: %TRUE if the channel was successfully ensure and (re-)dispatched,
> > + * otherwise %NULL.
> 
> s/ensure/ensured/, s/NULL/FALSE/ (the create variant also says NULL)

fixed.

I pushed an extra commit fixing a small issue I just spotted.

r+

Merged to master \o/