EServerSideSource: Evolution-Data-Server Reference Manual

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

## Functions

const gchar * | e_server_side_source_get_user_dir ()
GFile * | e_server_side_source_new_user_file ()
gchar * | e_server_side_source_uid_from_file ()
ESource * | e_server_side_source_new ()
ESource * | e_server_side_source_new_memory_only ()
gboolean | e_server_side_source_load ()
GFile * | e_server_side_source_get_file ()
GNode * | e_server_side_source_get_node ()
ESourceRegistryServer * | e_server_side_source_get_server ()
gboolean | e_server_side_source_get_exported ()
const gchar * | e_server_side_source_get_write_directory ()
void | e_server_side_source_set_write_directory ()
void | e_server_side_source_set_removable ()
void | e_server_side_source_set_writable ()
void | e_server_side_source_set_remote_creatable ()
void | e_server_side_source_set_remote_deletable ()
EOAuth2Support * | e_server_side_source_ref_oauth2_support ()
void | e_server_side_source_set_oauth2_support ()

## Types and Values

struct | EServerSideSource

## Object Hierarchy

        GObject
        ╰── ESource
            ╰── EServerSideSource

## Implemented Interfaces

EServerSideSource implements GInitable and GProxyResolver.

## Includes

    #include <libebackend/libebackend.h>

## Description

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

## Functions

### 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_util_generate_uid()`.

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.

#### Parameters

uid | unique identifier for a data source, or `NULL`. | [nullable]

#### Returns

the GFile for a new data source.

[transfer full]

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`.

#### Parameters

file | a GFile for a data source |
error | return location for a GError, or `NULL` |

#### Returns

the unique identity string for `file` , or `NULL`.

[nullable]

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`.

#### Parameters

server | an ESourceRegistryServer |
file | a GFile, or `NULL`. | [nullable]
error | return location for a GError, or `NULL` |

#### Returns

a new EServerSideSource, or `NULL`.

[nullable]

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.

#### Parameters

server | an ESourceRegistryServer |
uid | a unique identifier, or `NULL`. | [nullable]
error | return location for a GError, or `NULL` |

#### Returns

a new memory-only EServerSideSource, or `NULL` on error

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`.

#### Parameters

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.

#### Parameters

source | an EServerSideSource |

#### Returns

the GFile for `source` , or `NULL`.

[transfer none][nullable]

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.

#### Parameters

source | an EServerSideSource |

#### Returns

a GNode, or `NULL`.

[transfer none][nullable]

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.

#### Parameters

source | an EServerSideSource |

#### Returns

the ESourceRegistryServer for `source` .

[transfer none]

Since: 3.6

### 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` uid to `e_source_registry_server_ref_source()` (provided that `source` 's “parent” is also exported).

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

source | an EServerSideSource |

#### Returns

an EOAuth2Support object, or `NULL`.

[transfer full][nullable]

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.

#### Parameters

source | an EServerSideSource |
oauth2_support | an EOAuth2Support object, or `NULL`. | [nullable]

Since: 3.8

## Types and Values

### struct EServerSideSource

    struct EServerSideSource;

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

Since: 3.6