EServerSideSource

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

## Synopsis

    #include <libebackend/libebackend.h>

    struct              EServerSideSource;
    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);

## Object Hierarchy

      GObject
       +----ESource
             +----EServerSideSource

## Implemented Interfaces

EServerSideSource implements GInitable.

## Properties

      "allow-auth-prompt"        gboolean              : Read / Write / Construct
      "auth-session-type"        GType*                : Read / Write
      "exported"                 gboolean              : Read
      "file"                     GFile*                : Read / Write / Construct Only
      "oauth2-support"           EOAuth2Support*       : Read / Write
      "remote-creatable"         gboolean              : Read / Write
      "remote-deletable"         gboolean              : Read / Write
      "removable"                gboolean              : Read / Write
      "server"                   ESourceRegistryServer*  : Read / Write / Construct Only
      "writable"                 gboolean              : Read / Write
      "write-directory"          gchar*                : Read / Write

## Description

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

## Details

### struct EServerSideSource

    struct EServerSideSource;

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

Since 3.6

### 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

## Property Details

### The `"allow-auth-prompt"` property

      "allow-auth-prompt"        gboolean              : Read / Write / Construct

Whether authentication sessions may interrupt the user for a password.

Default value: TRUE

### The `"auth-session-type"` property

      "auth-session-type"        GType*                : Read / Write

The type of authentication session to instantiate for this source.

Allowed values: EAuthenticationSession

### The `"exported"` property

      "exported"                 gboolean              : Read

Whether the source has been exported over D-Bus.

Default value: FALSE

### The `"file"` property

      "file"                     GFile*                : Read / Write / Construct Only

The key file for the data source.

### The `"oauth2-support"` property

      "oauth2-support"           EOAuth2Support*       : Read / Write

The object providing OAuth 2.0 support.

### The `"remote-creatable"` property

      "remote-creatable"         gboolean              : Read / Write

Whether the data source can create remote resources.

Default value: FALSE

### The `"remote-deletable"` property

      "remote-deletable"         gboolean              : Read / Write

Whether the data source can delete remote resources.

Default value: FALSE

### The `"removable"` property

      "removable"                gboolean              : Read / Write

Whether the data source is removable.

Default value: FALSE

### The `"server"` property

      "server"                   ESourceRegistryServer*  : Read / Write / Construct Only

The server to which the data source belongs.

### The `"writable"` property

      "writable"                 gboolean              : Read / Write

Whether the data source is writable.

Default value: FALSE

### The `"write-directory"` property

      "write-directory"          gchar*                : Read / Write

Directory in which to write changes to disk.

Default value: NULL