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

Object Hierarchy

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

Implemented Interfaces

EServerSideSource implements GInitable.

Properties

  "allow-auth-prompt"        gboolean              : Read / Write / Construct
  "exported"                 gboolean              : Read
  "file"                     GFile*                : Read / Write / Construct Only
  "removable"                gboolean              : Read / Write
  "server"                   ESourceRegistryServer*  : Read / Write / Construct Only
  "uid"                      gchar*                : 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_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

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 "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 "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 "uid" property

  "uid"                      gchar*                : Read / Write / Construct Only

The unique identity of the data source.

Default value: NULL


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