GrssFeedsSubscriber: libgrss Reference Manual

## GrssFeedsSubscriber GrssFeedsSubscriber — feeds subscriber |

## Functions

GrssFeedsSubscriber * | grss_feeds_subscriber_new ()
gboolean | grss_feeds_subscriber_listen ()
GList * | grss_feeds_subscriber_get_listened ()
void | grss_feeds_subscriber_set_port ()
void | grss_feeds_subscriber_switch ()
GInetAddress * | grss_feeds_subscriber_get_address ()
int | grss_feeds_subscriber_get_port ()
SoupSession * | grss_feeds_subscriber_get_session ()

## Signals

void | notification-received | Run Last

## Types and Values

#define | GRSS_FEEDS_SUBSCRIBER_TYPE

## Object Hierarchy

        GObject
        ╰── GrssFeedsSubscriber

## Description

GrssFeedsSubscriber is an alternative for GrssFeedsPool, able to receive real-time notifications by feeds managed by one of the supported protocols. When the subscriber is executed (with `grss_feeds_subscriber_switch()`) it opens a server on a local port (configurable with `grss_feeds_subscriber_set_port()`), engage a subscription for each GrssFeedChannel passed with `grss_feeds_subscriber_listen()`, and waits for direct notifications by the remote server.

Pay attention to the fact this object doesn't provides any NAT traversing method to receive notification while behind a NAT.

## Functions

### grss_feeds_subscriber_new ()

    GrssFeedsSubscriber *
    grss_feeds_subscriber_new ();

Allocates a new GrssFeedsSubscriber.

#### Returns

a new GrssFeedsSubscriber.

### grss_feeds_subscriber_listen ()

    gboolean
    grss_feeds_subscriber_listen (GrssFeedsSubscriber *sub,
                                  GList *feeds);

To set the list of feeds to be managed by `sub` . The previous list, if any, is invalidated. After invokation to the function, `grss_feeds_subscriber_switch()` must be call to run the subscription. The list in `feeds` can be freed after calling this; linked GrssFeedChannel are g_object_ref'd here.

#### Parameters

sub | a GrssFeedsSubscriber. |
feeds | a list of GrssFeedChannel. | [element-type GrssFeedChannel]

#### Returns

`TRUE` if all GrssFeedChannels involved in `feeds` are valid and can be listened with one of the implemented procotols, `FALSE` otherwise.

### grss_feeds_subscriber_get_listened ()

    GList *
    grss_feeds_subscriber_get_listened (GrssFeedsSubscriber *sub);

Returns the list of feeds currently managed by `sub` .

#### Parameters

sub | a GrssFeedsSubscriber. |

#### Returns

a list of GrssFeedChannel, to be freed with `g_list_free()` when no longer in use. Do not modify elements found in this list.

[element-type GrssFeedChannel][transfer container]

### grss_feeds_subscriber_set_port ()

    void
    grss_feeds_subscriber_set_port (GrssFeedsSubscriber *sub,
                                    int port);

To customize the port opened by the local server to catch incoming publishers' events. By default this is 8444. Changing the port while the subscriber is running imply restart the local server. Pay attention to the fact many publishers' implementations accept only certain ports.

#### Parameters

sub | a GrssFeedsSubscriber. |
port | new listening port for the server. |

### grss_feeds_subscriber_switch ()

    void
    grss_feeds_subscriber_switch (GrssFeedsSubscriber *sub,
                                  gboolean run);

Permits to pause or resume `sub` listening for events.

#### Parameters

sub | a GrssFeedsSubscriber. |
run | `TRUE` to run the subscriber, `FALSE` to pause it. |

### grss_feeds_subscriber_get_address ()

    GInetAddress *
    grss_feeds_subscriber_get_address (GrssFeedsSubscriber *sub);

This function returns the Internet address where `sub` is listening for external events. It is often required by GrssFeedsSubscriberHandlers while subscribing contents to specify the local endpoint for communications.

#### Parameters

sub | a GrssFeedsSubscriber. |

#### Returns

the GInetAddress used by `sub` , or `NULL` if the GrssFeedsSubscriber is switched off.

[transfer none]

### grss_feeds_subscriber_get_port ()

    int
    grss_feeds_subscriber_get_port (GrssFeedsSubscriber *sub);

This function returns the Internet port where `sub` is listening for external events. It is often required by GrssFeedsSubscriberHandlers while subscribing contents to specify the local endpoint for communications.

#### Parameters

sub | a GrssFeedsSubscriber. |

#### Returns

the port of the socket locally opened by `sub` .

### grss_feeds_subscriber_get_session ()

    SoupSession *
    grss_feeds_subscriber_get_session (GrssFeedsSubscriber *sub);

To obtain the internal SoupSession of a GrssFeedsSubscriber, so to re-use it in GrssFeedsSubscriberHandlers or similar tasks.

#### Parameters

sub | a GrssFeedsSubscriber. |

#### Returns

the SoupSession used by the provided GrssFeedsSubscriber.

[transfer none]

## Types and Values

### GRSS_FEEDS_SUBSCRIBER_TYPE

    #define GRSS_FEEDS_SUBSCRIBER_TYPE		(grss_feeds_subscriber_get_type())

## Signal Details

### The `“notification-received”` signal

    void
    user_function (GrssFeedsSubscriber *pool,
                   GObject             *feed,
                   GObject             *item,
                   gpointer             user_data)

Emitted when a notification has been received and parsed. The `item` is cached and unref'd when the GrssFeedsSubscriber is destroyed or a new set of feeds is provided.

#### Parameters

pool | the GrssFeedsSubscriber emitting the signal. |
feed | the GrssFeedChannel which has been updated. |
item | the GrssFeedItem received. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last