Evolution-Data-Server Reference Manual: EServerSideSource

## 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_allow_auth_prompt ()
void | e_server_side_source_set_allow_auth_prompt ()
GType | e_server_side_source_get_auth_session_type ()
void | e_server_side_source_set_auth_session_type ()
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
struct | EServerSideSourceClass

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

#### Parameters

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

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

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

#### Parameters

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

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

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`

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`

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

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

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

Since 3.8

## Types and Values

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