Bug 28420

15:48 < smcv> cassidy: the only problem is Requested, which has no sensible 
              value for "I have no idea"
15:48 < cassidy> hum right :\
15:48 < smcv> cassidy: but Requested has been mandatory for ages and MC will 
              basically blow up without it
15:49 < smcv> cassidy: so I think it'd be OK to assume it was unrequested
15:50 < cassidy> yeah, new code which will use this new API will be fine

http://git.Collabora.co.uk/?p=user/cassidy/telepathy-glib;a=shortlog;h=refs/heads/channel-props-28420

> -  tp_debug_set_flags ("all");
> +  //tp_debug_set_flags ("all");

If you want to make this change (which would be entirely reasonable IMO), just delete the line.

(One day I'd like a mechanism to capture each debug log to a file, and cat them for each failed test; this is not that day, unless you're feeling tremendously enthusiastic.)

> +   * %TRUE if the channel has been requested.

I think this deserves better documentation: in practice, nobody notices that Requested is how you detect an "incoming"/"outgoing" channel. Perhaps something like this:

    %TRUE if this channel was created in response to a local request, such
    as a call to tp_account_channel_request_create_channel_async(). %FALSE
    if this channel was initiated by a remote contact
    (the #TpChannel:initiator-handle), or if it appeared as a side-effect
    of some other action.

    For instance, this is %FALSE on incoming calls and file transfers,
    remotely-initiated 1-1 text conversations, and invitations to chatrooms,
    and %TRUE on outgoing calls and file transfers, locally-initiated 1-1
    text conversations, and chatrooms joined by local user action.

> +   * The #TpHandle of the initiator of this channel.

I think it's worth expanding on this too:

    The %TP_HANDLE_TYPE_CONTACT #TpHandle of the initiator of this
    channel, or 0 if there is no particular initiator.

    If the channel was initiated by a remote contact, this handle represents
    that contact, and #TpChannel:requested will be %FALSE. For instance,
    for an incoming call this property indicates the caller, and for a
    chatroom invitation this property indicates who sent the invitation.

    If the channel was requested by the local user, #TpChannel:requested
    will be %TRUE, and this property may be the #TpChannel:group-self-handle
    or #TpConnection:self-handle.

    If the channel appeared for some other reason (for instance as a
    side-effect of connecting to the server), this property may be 0.

> +   * The identifier of the initiator of this channel.

    If #TpChannel:initiator-handle is 0, this will always be "".
    Otherwise, this will be the #TpContact:identifier of the contact
    with that handle.

Fixed (I squashed the changes).

Ship it!

Merged to master, will be in 0.11.15