WockyMetaPorter

## WockyMetaPorter WockyMetaPorter |

## Synopsis

                        WockyMetaPorter;
                        WockyMetaPorterClass;
                        WockyMetaPorterPrivate;
    enum                WockyMetaPorterError;
    GQuark              wocky_meta_porter_error_quark       (void);
    #define             WOCKY_META_PORTER_ERROR
    WockyPorter *       wocky_meta_porter_new               (const gchar *jid,
                                                             WockyContactFactory *contact_factory);
    guint16             wocky_meta_porter_get_port          (WockyMetaPorter *porter);
    void                wocky_meta_porter_hold              (WockyMetaPorter *porter,
                                                             WockyContact *contact);
    void                wocky_meta_porter_unhold            (WockyMetaPorter *porter,
                                                             WockyContact *contact);
    void                wocky_meta_porter_set_jid           (WockyMetaPorter *porter,
                                                             const gchar *jid);
    void                wocky_meta_porter_open_async        (WockyMetaPorter *porter,
                                                             WockyLLContact *contact,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            wocky_meta_porter_open_finish       (WockyMetaPorter *porter,
                                                             GAsyncResult *result,
                                                             GError **error);
    GSocketConnection * wocky_meta_porter_borrow_connection (WockyMetaPorter *porter,
                                                             WockyLLContact *contact);

## Object Hierarchy

      GObject
       +----WockyMetaPorter

## Implemented Interfaces

WockyMetaPorter implements WockyPorter.

## Properties

      "contact-factory"          WockyContactFactory*  : Read / Write / Construct Only

## Description

## Details

### WockyMetaPorter

    typedef struct _WockyMetaPorter WockyMetaPorter;

### WockyMetaPorterClass

    typedef struct {
      GObjectClass parent_class;
    } WockyMetaPorterClass;

### WockyMetaPorterPrivate

    typedef struct _WockyMetaPorterPrivate WockyMetaPorterPrivate;

### enum WockyMetaPorterError

    typedef enum
    {
      WOCKY_META_PORTER_ERROR_NO_CONTACT_ADDRESS,
      WOCKY_META_PORTER_ERROR_FAILED_TO_CLOSE,
    } WockyMetaPorterError;

### wocky_meta_porter_error_quark ()

    GQuark              wocky_meta_porter_error_quark       (void);

Returns : |

### WOCKY_META_PORTER_ERROR

    #define WOCKY_META_PORTER_ERROR (wocky_meta_porter_error_quark ())

### wocky_meta_porter_new ()

    WockyPorter *       wocky_meta_porter_new               (const gchar *jid,
                                                             WockyContactFactory *contact_factory);

Convenience function to create a new WockyMetaPorter object. The JID can be set later by using `wocky_meta_porter_set_jid()`.

`jid` : | the JID of the local user, or `NULL`
`contact_factory` : | a WockyContactFactory object
Returns : | a new WockyMetaPorter

### wocky_meta_porter_get_port ()

    guint16             wocky_meta_porter_get_port          (WockyMetaPorter *porter);

Returns the port `porter` is listening in on for new incoming XMPP connections, or 0 if it has not been started yet with `wocky_porter_start()`.

`porter` : | a WockyMetaPorter
Returns : | the port `porter` is listening in on for new incoming XMPP connections, or 0 if it has not been started.

### wocky_meta_porter_hold ()

    void                wocky_meta_porter_hold              (WockyMetaPorter *porter,
                                                             WockyContact *contact);

Increases the hold count of the porter to `contact` by one. This means that if there is a connection open to `contact` then it will not disconnected after a timeout. Note that calling this function does not mean a connection will be opened. The hold count on a contact survives across connections.

To decrement the hold count of the porter to `contact`, one must call `wocky_meta_porter_unhold()`.

`porter` : | a WockyMetaPorter
`contact` : | a WockyContact

### wocky_meta_porter_unhold ()

    void                wocky_meta_porter_unhold            (WockyMetaPorter *porter,
                                                             WockyContact *contact);

Decreases the hold count of the porter to `contact` by one. This means that if there is a connection open to `contact` and the hold count is zero, a connection timeout will be started.

`porter` : | a WockyMetaPorter
`contact` : | a WockyContact

### wocky_meta_porter_set_jid ()

    void                wocky_meta_porter_set_jid           (WockyMetaPorter *porter,
                                                             const gchar *jid);

Changes the local JID according to `porter`. Note that this function can only be called once, and only if `NULL` was passed to `wocky_meta_porter_new()` when creating `porter`. Calling it again will be a no-op.

`porter` : | a WockyMetaPorter
`jid` : | a new JID

### wocky_meta_porter_open_async ()

    void                wocky_meta_porter_open_async        (WockyMetaPorter *porter,
                                                             WockyLLContact *contact,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Make an asynchronous request to open a connection to `contact` if one is not already open. The hold count of the porter to `contact` will be incrememented and so after completion `wocky_meta_porter_unhold()` should be called on contact to release the hold.

When the request is complete, `callback` will be called and the user should call `wocky_meta_porter_open_finish()` to finish the request.

`porter` : | a WockyMetaPorter
`contact` : | the WockyLLContact
`cancellable` : | an optional GCancellable, or `NULL`
`callback` : | a callback to be called
`user_data` : | data for `callback`

### wocky_meta_porter_open_finish ()

    gboolean            wocky_meta_porter_open_finish       (WockyMetaPorter *porter,
                                                             GAsyncResult *result,
                                                             GError **error);

Finishes an asynchronous request to open a connection if one is not already open. See `wocky_meta_porter_open_async()` for more details.

`porter` : | a WockyMetaPorter
`result` : | the GAsyncResult
`error` : | an optional GError location to store an error message
Returns : | `TRUE` if the operation was a success, otherwise `FALSE`

### wocky_meta_porter_borrow_connection ()

    GSocketConnection * wocky_meta_porter_borrow_connection (WockyMetaPorter *porter,
                                                             WockyLLContact *contact);

Borrow the GSocketConnection of the porter to `contact`, if one exists, otherwise `NULL` will be returned.

Note that the connection returned should be reffed using `g_object_ref()` if it needs to be kept. However, it will still be operated on by the underlying WockyXmppConnection object so can close spontaneously unless `wocky_meta_porter_hold()` is called with `contact`.

`porter` : | a WockyMetaPorter
`contact` : | the WockyContact
Returns : | the GSocketConnection or `NULL` if no connection is open

## Property Details

### The `"contact-factory"` property

      "contact-factory"          WockyContactFactory*  : Read / Write / Construct Only

The WockyContactFactory object in use by this meta porter.