WockyContactFactory

## WockyContactFactory WockyContactFactory — creates and looks up WockyContact objects |

## Synopsis

    #include <wocky/wocky-contact-factory.h>

    struct              WockyContactFactoryClass;
    void                wocky_contact_factory_add_ll_contact
                                                            (WockyContactFactory *factory,
                                                             WockyLLContact *contact);
    WockyBareContact *  wocky_contact_factory_ensure_bare_contact
                                                            (WockyContactFactory *factory,
                                                             const gchar *bare_jid);
    WockyLLContact *    wocky_contact_factory_ensure_ll_contact
                                                            (WockyContactFactory *factory,
                                                             const gchar *jid);
    WockyResourceContact * wocky_contact_factory_ensure_resource_contact
                                                            (WockyContactFactory *factory,
                                                             const gchar *full_jid);
    GList *             wocky_contact_factory_get_ll_contacts
                                                            (WockyContactFactory *factory);
    WockyBareContact *  wocky_contact_factory_lookup_bare_contact
                                                            (WockyContactFactory *factory,
                                                             const gchar *bare_jid);
    WockyLLContact *    wocky_contact_factory_lookup_ll_contact
                                                            (WockyContactFactory *factory,
                                                             const gchar *jid);
    WockyResourceContact * wocky_contact_factory_lookup_resource_contact
                                                            (WockyContactFactory *factory,
                                                             const gchar *full_jid);
    WockyContactFactory * wocky_contact_factory_new         (void);

## Description

Provides a way to create WockyContact objects. The objects created this way are cached by the factory and you can eventually look them up without creating them again.

## Details

### struct WockyContactFactoryClass

    struct WockyContactFactoryClass {
    };

The class of a WockyContactFactory.

### wocky_contact_factory_add_ll_contact ()

    void                wocky_contact_factory_add_ll_contact
                                                            (WockyContactFactory *factory,
                                                             WockyLLContact *contact);

Adds `contact` to the contact factory.

`factory` : | a WockyContactFactory instance
`contact` : | a WockyLLContact

### wocky_contact_factory_ensure_bare_contact ()

    WockyBareContact *  wocky_contact_factory_ensure_bare_contact
                                                            (WockyContactFactory *factory,
                                                             const gchar *bare_jid);

Returns an instance of WockyBareContact for `bare_jid`. The factory cache is used, but if the contact is not found in the cache, a new WockyBareContact is created and cached for future use.

`factory` : | a WockyContactFactory instance
`bare_jid` : | the JID of a bare contact
Returns : | a new reference to a WockyBareContact instance, which the caller is expected to release with `g_object_unref()` after use.

### wocky_contact_factory_ensure_ll_contact ()

    WockyLLContact *    wocky_contact_factory_ensure_ll_contact
                                                            (WockyContactFactory *factory,
                                                             const gchar *jid);

Returns an instance of WockyLLContact for `jid`. The factory cache is used, but if the contact is not found in the cache, a new WockyLLContact is created and cached for future use.

`factory` : | a WockyContactFactory instance
`jid` : | the JID of a contact
Returns : | a new reference to a WockyLLContact instance, which the caller is expected to release with `g_object_unref()` after use.

### wocky_contact_factory_ensure_resource_contact ()

    WockyResourceContact * wocky_contact_factory_ensure_resource_contact
                                                            (WockyContactFactory *factory,
                                                             const gchar *full_jid);

Returns an instance of WockyResourceContact for `full_jid`. The factory cache is used, but if the resource is not found in the cache, a new WockyResourceContact is created and cached for future use.

`factory` : | a WockyContactFactory instance
`full_jid` : | the full JID of a resource
Returns : | a new reference to a WockyResourceContact instance, which the caller is expected to release with `g_object_unref()` after use.

### wocky_contact_factory_get_ll_contacts ()

    GList *             wocky_contact_factory_get_ll_contacts
                                                            (WockyContactFactory *factory);

`factory` : | a WockyContactFactory instance
Returns : | a newly allocated GList of WockyLLContacts which should be freed using `g_list_free()`.

### wocky_contact_factory_lookup_bare_contact ()

    WockyBareContact *  wocky_contact_factory_lookup_bare_contact
                                                            (WockyContactFactory *factory,
                                                             const gchar *bare_jid);

Looks up if there's a WockyBareContact for `bare_jid` in the cache, and returns it if it's found.

`factory` : | a WockyContactFactory instance
`bare_jid` : | the JID of a bare contact
Returns : | a borrowed WockyBareContact instance (which the caller should reference with `g_object_ref()` if it will be kept), or `NULL` if the contact is not found.

### wocky_contact_factory_lookup_ll_contact ()

    WockyLLContact *    wocky_contact_factory_lookup_ll_contact
                                                            (WockyContactFactory *factory,
                                                             const gchar *jid);

Looks up if there's a WockyLLContact for `jid` in the cache, and returns it if it's found.

`factory` : | a WockyContactFactory instance
`jid` : | the JID of a contact
Returns : | a borrowed WockyLLContact instance (which the caller should reference with `g_object_ref()` if it will be kept), or `NULL` if the contact is not found.

### wocky_contact_factory_lookup_resource_contact ()

    WockyResourceContact * wocky_contact_factory_lookup_resource_contact
                                                            (WockyContactFactory *factory,
                                                             const gchar *full_jid);

Looks up if there's a WockyResourceContact for `full_jid` in the cache, and returns it if it's found.

`factory` : | a WockyContactFactory instance
`full_jid` : | the full JID of a resource
Returns : | a borrowed WockyResourceContact instance (which the caller should reference with `g_object_ref()` if it will be kept), or `NULL` if the contact is not found.

### wocky_contact_factory_new ()

    WockyContactFactory * wocky_contact_factory_new         (void);

Convenience function to create a new WockyContactFactory object.

Returns : | a newly created instance of WockyContactFactory