## EServerSideSource EServerSideSource — A server-side data source |

## Synopsis

    #include <libebackend/libebackend.h>

    struct              EServerSideSource;
    struct              EServerSideSourceClass;
    const gchar *       e_server_side_source_get_user_dir   (void);
    GFile *             e_server_side_source_new_user_file  (const gchar *uid);
    gchar *             e_server_side_source_uid_from_file  (GFile *file,
                                                             GError **error);
    ESource *           e_server_side_source_new            (ESourceRegistryServer *server,
                                                             GFile *file,
                                                             GError **error);
    ESource *           e_server_side_source_new_memory_only
                                                            (ESourceRegistryServer *server,
                                                             const gchar *uid,
                                                             GError **error);
    gboolean            e_server_side_source_load           (EServerSideSource *source,
                                                             GCancellable *cancellable,
                                                             GError **error);
    GFile *             e_server_side_source_get_file       (EServerSideSource *source);
    GNode *             e_server_side_source_get_node       (EServerSideSource *source);
    ESourceRegistryServer * e_server_side_source_get_server (EServerSideSource *source);
    gboolean            e_server_side_source_get_allow_auth_prompt
                                                            (EServerSideSource *source);
    void                e_server_side_source_set_allow_auth_prompt
                                                            (EServerSideSource *source,
                                                             gboolean allow_auth_prompt);
    GType               e_server_side_source_get_auth_session_type
                                                            (EServerSideSource *source);
    void                e_server_side_source_set_auth_session_type
                                                            (EServerSideSource *source,
                                                             GType auth_session_type);
    gboolean            e_server_side_source_get_exported   (EServerSideSource *source);
    const gchar *       e_server_side_source_get_write_directory
                                                            (EServerSideSource *source);
    void                e_server_side_source_set_write_directory
                                                            (EServerSideSource *source,
                                                             const gchar *write_directory);
    void                e_server_side_source_set_removable  (EServerSideSource *source,
                                                             gboolean removable);
    void                e_server_side_source_set_writable   (EServerSideSource *source,
                                                             gboolean writable);
    void                e_server_side_source_set_remote_creatable
                                                            (EServerSideSource *source,
                                                             gboolean remote_creatable);
    void                e_server_side_source_set_remote_deletable
                                                            (EServerSideSource *source,
                                                             gboolean remote_deletable);
    EOAuth2Support *    e_server_side_source_ref_oauth2_support
                                                            (EServerSideSource *source);
    void                e_server_side_source_set_oauth2_support
                                                            (EServerSideSource *source,
                                                             EOAuth2Support *oauth2_support);

## Description

An EServerSideSource is an ESource with some additional capabilities exclusive to the registry D-Bus service.

## Details

### struct EServerSideSource

    struct EServerSideSource {
    	ESource parent;
    	EServerSideSourcePrivate *priv;
    };

Contains only private data that should be read and manipulated using the functions below.

Since 3.6

### struct EServerSideSourceClass

    struct EServerSideSourceClass {
    	ESourceClass parent_class;
    };

### e_server_side_source_get_user_dir ()

    const gchar *       e_server_side_source_get_user_dir   (void);

Returns the directory where user-specific data source files are stored.

Returns : | the user-specific data source directory

Since 3.6

### e_server_side_source_new_user_file ()

    GFile *             e_server_side_source_new_user_file  (const gchar *uid);

Generates a unique file name for a new user-specific data source. If `uid` is non-`NULL` it will be used in the basename of the file, otherwise a unique basename will be generated using `e_uid_new()`.

The returned GFile can then be passed to `e_server_side_source_new()`. Unreference the GFile with `g_object_unref()` when finished with it.

Note the data source file itself is not created here, only its name.

`uid` : | unique identifier for a data source, or `NULL`
Returns : | the GFile for a new data source

Since 3.6

### e_server_side_source_uid_from_file ()

    gchar *             e_server_side_source_uid_from_file  (GFile *file,
                                                             GError **error);

Extracts a unique identity string from the base name of `file`. If the base name of `file` is missing a '.source' extension, the function sets `error` and returns `NULL`.

`file` : | a GFile for a data source
`error` : | return location for a GError, or `NULL`
Returns : | the unique identity string for `file`, or `NULL`

Since 3.6

### e_server_side_source_new ()

    ESource *           e_server_side_source_new            (ESourceRegistryServer *server,
                                                             GFile *file,
                                                             GError **error);

Creates a new EServerSideSource which belongs to `server`. If `file` is non-`NULL` and points to an existing file, the EServerSideSource is initialized from the file content. If a read error occurs or the file contains syntax errors, the function sets `error` and returns `NULL`.

`server` : | an ESourceRegistryServer
`file` : | a GFile, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | a new EServerSideSource, or `NULL`

Since 3.6

### e_server_side_source_new_memory_only ()

    ESource *           e_server_side_source_new_memory_only
                                                            (ESourceRegistryServer *server,
                                                             const gchar *uid,
                                                             GError **error);

Creates a memory-only EServerSideSource which belongs to `server`. No on-disk key file is created for this data source, so it will not be remembered across sessions.

Data source collections are often populated with memory-only data sources to serve as proxies for resources discovered on a remote server. These data sources are usually neither "writable" nor "removable" by clients, at least not directly.

If an error occurs while instantiating the EServerSideSource, the function sets `error` and returns `NULL`. Although at this time there are no known error conditions for memory-only data sources.

`server` : | an ESourceRegistryServer
`uid` : | a unique identifier, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | a new memory-only EServerSideSource, or `NULL`

Since 3.6

### e_server_side_source_load ()

    gboolean            e_server_side_source_load           (EServerSideSource *source,
                                                             GCancellable *cancellable,
                                                             GError **error);

Reloads data source content from the file pointed to by the "file" property.

If the "file" property is `NULL` or the file it points to does not exist, the function does nothing and returns `TRUE`.

If a read error occurs or the file contains syntax errors, the function sets `error` and returns `FALSE`.

`source` : | an EServerSideSource
`cancellable` : | optional GCancellable object, or `NULL`
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

Since 3.6

### e_server_side_source_get_file ()

    GFile *             e_server_side_source_get_file       (EServerSideSource *source);

Returns the GFile from which data source content is loaded and to which changes are saved. Note the `source` may not have a GFile.

`source` : | an EServerSideSource
Returns : | the GFile for `source`, or `NULL`

Since 3.6

### e_server_side_source_get_node ()

    GNode *             e_server_side_source_get_node       (EServerSideSource *source);

Returns the GNode representing the `source`'s hierarchical placement, or `NULL` if `source` has not been placed in the data source hierarchy. The data member of the GNode points back to `source`. This is an easy way to traverse ancestor and descendant data sources.

Note that accessing other data sources this way is not thread-safe, and this therefore function may be replaced at some later date.

`source` : | an EServerSideSource
Returns : | a GNode, or `NULL`

Since 3.6

### e_server_side_source_get_server ()

    ESourceRegistryServer * e_server_side_source_get_server (EServerSideSource *source);

Returns the ESourceRegistryServer to which `source` belongs.

`source` : | an EServerSideSource
Returns : | the ESourceRegistryServer for `source`

Since 3.6

### e_server_side_source_get_allow_auth_prompt ()

    gboolean            e_server_side_source_get_allow_auth_prompt
                                                            (EServerSideSource *source);

Returns whether an authentication prompt is allowed to be shown for `source`. EAuthenticationSession will honor this setting by dismissing the session if it can't find a valid stored password.

See `e_server_side_source_set_allow_auth_prompt()` for further discussion.

`source` : | an EServerSideSource
Returns : | whether auth prompts are allowed for `source`

Since 3.6

### e_server_side_source_set_allow_auth_prompt ()

    void                e_server_side_source_set_allow_auth_prompt
                                                            (EServerSideSource *source,
                                                             gboolean allow_auth_prompt);

Sets whether an authentication prompt is allowed to be shown for `source`. EAuthenticationSession will honor this setting by dismissing the session if it can't find a valid stored password.

If the user declines to provide a password for `source` when prompted by an EAuthenticationSession, the ESourceRegistryServer will set this property to `FALSE` to suppress any further prompting, which would likely annoy the user. However when an ESourceRegistry instance is created by a client application, the first thing it does is reset this property to `TRUE` for all registered data sources. So suppressing authentication prompts is only ever temporary.

`source` : | an EServerSideSource
`allow_auth_prompt` : | whether auth prompts are allowed for `source`

Since 3.6

### e_server_side_source_get_auth_session_type ()

    GType               e_server_side_source_get_auth_session_type
                                                            (EServerSideSource *source);

Returns the type of authentication session to use for `source`, which will get passed to `e_source_registry_server_authenticate()`.

This defaults to the GType for EAuthenticationSession.

`source` : | an EServerSideSource
Returns : | the type of authentication session to use for `source`

Since 3.8

### e_server_side_source_set_auth_session_type ()

    void                e_server_side_source_set_auth_session_type
                                                            (EServerSideSource *source,
                                                             GType auth_session_type);

Sets the type of authentication session to use for `source`, which will get passed to `e_source_registry_server_authenticate()`.

`auth_session_type` must be derived from EAuthenticationSession, or else the function will reject the GType with a runtime warning.

This defaults to the GType for EAuthenticationSession.

`source` : | an EServerSideSource
`auth_session_type` : | the type of authentication session to use for `source`

Since 3.8

### e_server_side_source_get_exported ()

    gboolean            e_server_side_source_get_exported   (EServerSideSource *source);

Returns whether `source` has been exported over D-Bus.

The function returns `FALSE` after `source` is initially created, `TRUE` after passing `source` to `e_source_registry_add_source()` (provided that `source`'s "parent" is also exported), and `FALSE` after passing `source` to `e_source_registry_remove_source()`.

`source` : | an EServerSideSource
Returns : | whether `source` has been exported

Since 3.6

### e_server_side_source_get_write_directory ()

    const gchar *       e_server_side_source_get_write_directory
                                                            (EServerSideSource *source);

Returns the local directory path where changes to `source` are written.

By default, changes are written to the local directory path returned by `e_server_side_source_get_user_dir()`, but an ECollectionBackend may wish to override this to use its own private cache directory for data sources it creates automatically.

`source` : | an EServerSideSource
Returns : | the directory where changes are written

Since 3.6

### e_server_side_source_set_write_directory ()

    void                e_server_side_source_set_write_directory
                                                            (EServerSideSource *source,
                                                             const gchar *write_directory);

Sets the local directory path where changes to `source` are to be written.

By default, changes are written to the local directory path returned by `e_server_side_source_get_user_dir()`, but an ECollectionBackend may wish to override this to use its own private cache directory for data sources it creates automatically.

`source` : | an EServerSideSource
`write_directory` : | the directory where changes are to be written

Since 3.6

### e_server_side_source_set_removable ()

    void                e_server_side_source_set_removable  (EServerSideSource *source,
                                                             gboolean removable);

Sets whether to allow registry clients to remove `source` and its descendants. If `TRUE`, the Removable D-Bus interface is exported at the object path for `source`. If `FALSE`, the Removable D-Bus interface is unexported at the object path for `source`, and any attempt by clients to call `e_source_remove()` will fail.

Note this is only enforced for clients of the registry D-Bus service. The service itself may remove any data source at any time.

`source` : | an EServerSideSource
`removable` : | whether to export the Removable interface

Since 3.6

### e_server_side_source_set_writable ()

    void                e_server_side_source_set_writable   (EServerSideSource *source,
                                                             gboolean writable);

Sets whether to allow registry clients to alter the content of `source`. If `TRUE`, the Writable D-Bus interface is exported at the object path for `source`. If `FALSE`, the Writable D-Bus interface is unexported at the object path for `source`, and any attempt by clients to call `e_source_write()` will fail.

Note this is only enforced for clients of the registry D-Bus service. The service itself can write to any data source at any time.

`source` : | an EServerSideSource
`writable` : | whether to export the Writable interface

Since 3.6

### e_server_side_source_set_remote_creatable ()

    void                e_server_side_source_set_remote_creatable
                                                            (EServerSideSource *source,
                                                             gboolean remote_creatable);

Indicates whether `source` can be used to create resources on a remote server. Typically this is only set to `TRUE` for collection sources.

If `TRUE`, the RemoteCreatable D-Bus interface is exported at the object path for `source`. If `FALSE`, the RemoteCreatable D-Bus interface is unexported at the object path for `source`, and any attempt by clients to call `e_source_remote_create()` will fail.

Unlike the "removable" and "writable" properties, this is enforced for both clients of the registry D-Bus service and within the registry D-Bus service itself.

`source` : | an EServerSideSource
`remote_creatable` : | whether to export the RemoteCreatable interface

Since 3.6

### e_server_side_source_set_remote_deletable ()

    void                e_server_side_source_set_remote_deletable
                                                            (EServerSideSource *source,
                                                             gboolean remote_deletable);

Indicates whether `source` can be used to delete resources on a remote server. Typically this is only set to `TRUE` for sources created by an ECollectionBackend to represent a remote resource.

If `TRUE`, the RemoteDeletable D-Bus interface is exported at the object path for `source`. If `FALSE`, the RemoteDeletable D-Bus interface is unexported at the object path for `source`, and any attempt by clients to call `e_source_remote_delete()` will fail.

Unlike the "removable" and "writable" properties, this is enforced for both clients of the registry D-Bus server and within the registry D-Bus service itself.

`source` : | an EServerSideSource
`remote_deletable` : | whether to export the RemoteDeletable interface

Since 3.6

### e_server_side_source_ref_oauth2_support ()

    EOAuth2Support *    e_server_side_source_ref_oauth2_support
                                                            (EServerSideSource *source);

Returns the object implementing the EOAuth2SupportInterface, or `NULL` if `source` does not support OAuth 2.0 authentication.

The returned EOAuth2Support object is referenced for thread-safety. Unreference the object with `g_object_unref()` when finished with it.

`source` : | an EServerSideSource
Returns : | an EOAuth2Support object, or `NULL`

Since 3.8

### e_server_side_source_set_oauth2_support ()

    void                e_server_side_source_set_oauth2_support
                                                            (EServerSideSource *source,
                                                             EOAuth2Support *oauth2_support);

Indicates whether `source` supports OAuth 2.0 authentication.

If `oauth2_support` is non-`NULL`, the OAuth2Support D-Bus interface is exported at the object path for `source`. If `oauth2_support` is `NULL`, the OAuth2Support D-Bus interface is unexported at the object path for `source`, and any attempt by clients to call `e_source_get_oauth2_access_token()` will fail.

Requests for OAuth 2.0 access tokens are forwarded to `oauth2_support`, which implements the EOAuth2SupportInterface.

`source` : | an EServerSideSource
`oauth2_support` : | an EOAuth2Support object, or `NULL`

Since 3.8