Evolution-Data-Server Manual: Backend Utilities (libebackend) | ||||
---|---|---|---|---|
Top | Description | Object Hierarchy | Implemented Interfaces | Properties |
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
);
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.
|
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
.
|
a GFile for a data source |
|
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
.
|
an ESourceRegistryServer |
|
a GFile, or NULL
|
|
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.
|
an ESourceRegistryServer |
|
a unique identifier, or NULL
|
|
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
.
|
an EServerSideSource |
|
optional GCancellable object, or NULL
|
|
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.
|
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.
|
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.
|
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.
|
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.
|
an EServerSideSource |
|
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.
|
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.
|
an EServerSideSource |
|
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()
.
|
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.
|
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.
|
an EServerSideSource |
|
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.
|
an EServerSideSource |
|
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.
|
an EServerSideSource |
|
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.
|
an EServerSideSource |
|
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.
|
an EServerSideSource |
|
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.
|
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.
|
an EServerSideSource |
|
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 "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