EDataServer.Source

g EDataServer.Source EDataServer.Source GObject.GInterface GObject.GInterface Gio.Initable Gio.Initable GObject.GInterface->Gio.Initable Gio.ProxyResolver Gio.ProxyResolver GObject.GInterface->Gio.ProxyResolver GObject.Object GObject.Object GObject.Object->EDataServer.Source Gio.Initable->EDataServer.Source Gio.ProxyResolver->EDataServer.Source

Subclasses:None

Methods

Inherited:GObject.Object (37), Gio.Initable (2), Gio.ProxyResolver (5)
Structs:GObject.ObjectClass (5)
class new (dbus_object, main_context)
class new_with_uid (uid, main_context)
class parameter_to_key (param_name)
  camel_configure_service (service)
  changed ()
  compare_by_display_name (source2)
  delete_password (cancellable, callback, *user_data)
  delete_password_finish (result)
  delete_password_sync (cancellable)
  dup_display_name ()
  dup_parent ()
  dup_secret_label ()
  dup_uid ()
  emit_credentials_required (reason, certificate_pem, certificate_errors, op_error)
  equal (source2)
  get_connection_status ()
  get_display_name ()
  get_enabled ()
  get_extension (extension_name)
  get_last_credentials_required_arguments (cancellable, callback, *user_data)
  get_last_credentials_required_arguments_finish (result)
  get_last_credentials_required_arguments_sync (cancellable)
  get_oauth2_access_token (cancellable, callback, *user_data)
  get_oauth2_access_token_finish (result)
  get_oauth2_access_token_sync (cancellable)
  get_parent ()
  get_remote_creatable ()
  get_remote_deletable ()
  get_removable ()
  get_uid ()
  get_writable ()
  has_extension (extension_name)
  hash ()
  invoke_authenticate (credentials, cancellable, callback, *user_data)
  invoke_authenticate_finish (result)
  invoke_authenticate_sync (credentials, cancellable)
  invoke_credentials_required (reason, certificate_pem, certificate_errors, op_error, cancellable, callback, *user_data)
  invoke_credentials_required_finish (result)
  invoke_credentials_required_sync (reason, certificate_pem, certificate_errors, op_error, cancellable)
  lookup_password (cancellable, callback, *user_data)
  lookup_password_finish (result)
  lookup_password_sync (cancellable)
  mail_signature_load (io_priority, cancellable, callback, *user_data)
  mail_signature_load_finish (result)
  mail_signature_load_sync (cancellable)
  mail_signature_replace (contents, length, io_priority, cancellable, callback, *user_data)
  mail_signature_replace_finish (result)
  mail_signature_replace_sync (contents, length, cancellable)
  mail_signature_symlink (symlink_target, io_priority, cancellable, callback, *user_data)
  mail_signature_symlink_finish (result)
  mail_signature_symlink_sync (symlink_target, cancellable)
  proxy_lookup (uri, cancellable, callback, *user_data)
  proxy_lookup_finish (result)
  proxy_lookup_sync (uri, cancellable)
  ref_dbus_object ()
  ref_main_context ()
  refresh_add_timeout (context, callback, *user_data)
  refresh_force_timeout ()
  refresh_remove_timeout (refresh_timeout_id)
  refresh_remove_timeouts_by_data (user_data)
  remote_create (scratch_source, cancellable, callback, *user_data)
  remote_create_finish (result)
  remote_create_sync (scratch_source, cancellable)
  remote_delete (cancellable, callback, *user_data)
  remote_delete_finish (result)
  remote_delete_sync (cancellable)
  remove (cancellable, callback, *user_data)
  remove_finish (result)
  remove_sync (cancellable)
  set_connection_status (connection_status)
  set_display_name (display_name)
  set_enabled (enabled)
  set_parent (parent)
  store_password (password, permanently, cancellable, callback, *user_data)
  store_password_finish (result)
  store_password_sync (password, permanently, cancellable)
  to_string (length)
  unset_last_credentials_required_arguments (cancellable, callback, *user_data)
  unset_last_credentials_required_arguments_finish (result)
  unset_last_credentials_required_arguments_sync (cancellable)
  write (cancellable, callback, *user_data)
  write_finish (result)
  write_sync (cancellable)

Virtual Methods

Inherited:GObject.Object (7), Gio.Initable (1), Gio.ProxyResolver (4)
  do_authenticate (credentials)
  do_changed ()
  do_credentials_required (reason, certificate_pem, certificate_errors, op_error)
  do_get_oauth2_access_token (cancellable, callback, *user_data)
  do_get_oauth2_access_token_finish (result)
  do_get_oauth2_access_token_sync (cancellable)
  do_invoke_authenticate_impl (dbus_source, arg_credentials, cancellable)
  do_invoke_credentials_required_impl (dbus_source, arg_reason, arg_certificate_pem, arg_certificate_errors, arg_dbus_error_name, arg_dbus_error_message, cancellable)
  do_remote_create (scratch_source, cancellable, callback, *user_data)
  do_remote_create_finish (result)
  do_remote_create_sync (scratch_source, cancellable)
  do_remote_delete (cancellable, callback, *user_data)
  do_remote_delete_finish (result)
  do_remote_delete_sync (cancellable)
  do_remove (cancellable, callback, *user_data)
  do_remove_finish (result)
  do_remove_sync (cancellable)
  do_unset_last_credentials_required_arguments_impl (cancellable)
  do_write (cancellable, callback, *user_data)
  do_write_finish (result)
  do_write_sync (cancellable)

Properties

Name Type Flags Short Description
connection-status EDataServer.SourceConnectionStatus r Connection status of the source
display-name str r/w/c/en The human-readable name of the data source
enabled bool r/w/c/en Whether the data source is enabled
main-context GLib.MainContext r/w/co The main loop context on which to attach event sources
parent str r/w/en The unique identity of the parent data source
remote-creatable bool r Whether the data source can create remote resources
remote-deletable bool r Whether the data source can delete remote resources
removable bool r Whether the data source is removable
uid str r/w/co The unique identity of the data source
writable bool r Whether the data source is writable

Signals

Inherited:GObject.Object (1)
Name Short Description
authenticate Let’s the backend know provided credentials to use to login to (possibly remote) data store.
changed The ::changed signal is emitted when a property in source or one of its extension objects changes.
credentials-required The ::credentials-required signal is emitted when the source requires credentials to connect to (possibly remote) data store.

Fields

Inherited:GObject.Object (1)
Name Type Access Description
parent GObject.Object r  

Class Details

class EDataServer.Source(**kwargs)
Bases:GObject.Object, Gio.Initable, Gio.ProxyResolver
Abstract:No
Structure:EDataServer.SourceClass

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

New in version 3.6.

classmethod new(dbus_object, main_context)
Parameters:
Raises:

GLib.Error

Returns:

a new EDataServer.Source, or None on error

Return type:

EDataServer.Source

Creates a new EDataServer.Source instance.

The EDataServer.Source ::changed signal will be emitted from main_context if given, or else from the thread-default GLib.MainContext at the time this function is called.

The only time the function should be called outside of EDataServer.SourceRegistry is to create a so-called “scratch” EDataServer.Source for editing in a Properties window or an account setup assistant.

FIXME: Elaborate on scratch sources.

New in version 3.6.

classmethod new_with_uid(uid, main_context)
Parameters:
Raises:

GLib.Error

Returns:

a new scratch EDataServer.Source, or None on error

Return type:

EDataServer.Source

Creates a new “scratch” EDataServer.Source with a predetermined unique identifier.

The EDataServer.Source ::changed signal will be emitted from main_context if given, or else from the thread-default GLib.MainContext at the time this function is called.

New in version 3.6.

classmethod parameter_to_key(param_name)
Parameters:param_name (str) – a GObject.ParamSpec name
Return type:str

Converts a GObject.ParamSpec name (e.g. “foo-bar” or “foo_bar”) to “CamelCase” for use as a GLib.KeyFile key (e.g. “FooBar”).

This function is made public only to aid in account migration. Applications should not need to use this.

New in version 3.6.

camel_configure_service(service)
Parameters:service (Camel.Service) – a Camel.Service

This function essentially glues together self and serivce so their configuration settings stay synchronized. The glue itself is a shared Camel.Settings instance.

Call this function immediately after creating a new Camel.Service with Camel.Session.add_service().

New in version 3.6.

changed()

Emits the EDataServer.Source ::changed signal from an idle callback in self’s EDataServer.Source :main-context.

This function is primarily intended for use by EDataServer.SourceExtension when emitting a GObject.Object ::notify signal on one of its properties.

New in version 3.6.

compare_by_display_name(source2)
Parameters:source2 (EDataServer.Source) – the second EDataServer.Source
Returns:a negative value if self compares before source2, zero if they compare equal, or a positive value if self compares after source2
Return type:int

Compares two EDataServer.Source instances by their display names. Useful for ordering sources in a user interface.

New in version 3.6.

delete_password(cancellable, callback, *user_data)
Parameters:

Asynchronously deletes the password for self from either the default keyring or session keyring. This operation does not rely on the registry service and therefore works for any EDataServer.Source – registered or “scratch”.

When the operation is finished, callback will be called. You can then call EDataServer.Source.delete_password_finish() to get the result of the operation.

New in version 3.12.

delete_password_finish(result)
Parameters:result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:GLib.Error
Returns:True on success, False on error
Return type:bool

Finishes the operation started with EDataServer.Source.delete_password().

Note the boolean return value indicates whether the delete operation itself completed successfully, not whether a password was found and deleted. If no password was found, the function will still return True. If an error occurs, the function sets error and returns False.

New in version 3.12.

delete_password_sync(cancellable)
Parameters:cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
Raises:GLib.Error
Returns:True on success, False on error
Return type:bool

Deletes the password for self from either the default keyring or session keyring. This operation does not rely on the registry service and therefore works for any EDataServer.Source – registered or “scratch”.

Note the boolean return value indicates whether the delete operation itself completed successfully, not whether a password was found and deleted. If no password was found, the function will still return True. If an error occurs, the function sets error and returns False.

New in version 3.12.

dup_display_name()
Returns:a newly-allocated copy of EDataServer.Source :display-name
Return type:str

Thread-safe variation of EDataServer.Source.get_display_name(). Use this function when accessing self from multiple threads.

The returned string should be freed with GLib.free() when no longer needed.

New in version 3.6.

dup_parent()
Returns:a newly-allocated copy of EDataServer.Source :parent
Return type:str

Thread-safe variation of EDataServer.Source.get_parent(). Use this function when accessing self from multiple threads.

The returned string should be freed with GLib.free() when no longer needed.

New in version 3.6.

dup_secret_label()
Returns:a newly-allocated secret label
Return type:str

Creates a label string based on self’s EDataServer.Source :display-name for use with #SecretItem.

New in version 3.12.

dup_uid()
Returns:a newly-allocated copy of EDataServer.Source :uid
Return type:str

Thread-safe variation of EDataServer.Source.get_uid(). Use this function when accessing self from multiple threads.

The returned string should be freed with GLib.free() when no longer needed.

New in version 3.6.

emit_credentials_required(reason, certificate_pem, certificate_errors, op_error)
Parameters:

Emits localy (in this process only) the EDataServer.Source ::credentials-required signal with given parameters. That’s the difference with EDataServer.Source.invoke_credentials_required(), which calls the signal globally, within each client.

New in version 3.16.

equal(source2)
Parameters:source2 (EDataServer.Source) – the second EDataServer.Source
Returns:True if self and source2 are equal
Return type:bool

Checks two EDataServer.Source instances for equality. EDataServer.Source instances are equal if their unique identifier strings are equal.

New in version 3.6.

get_connection_status()
Returns:Current connection status of the self.
Return type:EDataServer.SourceConnectionStatus

Obtain current connection status of the self.

New in version 3.16.

get_display_name()
Returns:the display name for self
Return type:str

Returns the display name for self. Use the display name to represent the EDataServer.Source in a user interface.

New in version 3.6.

get_enabled()
Returns:whether self is enabled
Return type:bool

Returns True if self is enabled.

An application should try to honor this setting if at all possible, even if it does not provide a way to change the setting through its user interface. Disabled data sources should generally be hidden.

This function does not take into account self’s ancestors in the EDataServer.Source hierarchy, each of which have their own enabled state. If any of self’s ancestors are disabled, then self itself should be treated as disabled. Use EDataServer.SourceRegistry.check_enabled() to easily check for this.

New in version 3.6.

get_extension(extension_name)
Parameters:extension_name (str) – an extension name
Returns:an instance of some EDataServer.SourceExtension subclass
Return type:EDataServer.SourceExtension

Returns an instance of some EDataServer.SourceExtension subclass which registered itself under extension_name. If no such instance exists within self, one will be created. It is the caller’s responsibility to know which subclass is being returned.

If you just want to test for the existence of an extension within self without creating it, use EDataServer.Source.has_extension().

Extension instances are owned by their EDataServer.Source and should not be referenced directly. Instead, reference the EDataServer.Source instance and use this function to fetch the extension instance as needed.

New in version 3.6.

get_last_credentials_required_arguments(cancellable, callback, *user_data)
Parameters:

Asynchronously calls the GetLastCredentialsRequiredArguments method on the server side, to get the last values used for the ‘credentials-required’ signal. See EDataServer.Source.get_last_credentials_required_arguments_sync() for more information.

When the operation is finished, callback will be called. You can then call EDataServer.Source.get_last_credentials_required_arguments_finish() to get the result of the operation.

New in version 3.16.

get_last_credentials_required_arguments_finish(result)
Parameters:result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:GLib.Error
Returns:True on success, False on error
out_reason:an EDataServer.SourceCredentialsReason, why the credentials are required
out_certificate_pem:
 PEM-encoded secure connection certificate, or an empty string
out_certificate_errors:
 a bit-or of Gio.TlsCertificateFlags for secure connection certificate
out_op_error:a GLib.Error with a description of the previous credentials error
Return type:(bool, out_reason: EDataServer.SourceCredentialsReason, out_certificate_pem: str, out_certificate_errors: Gio.TlsCertificateFlags, out_op_error: GLib.Error)

Finishes the operation started with EDataServer.Source.get_last_credentials_required_arguments(). See EDataServer.Source.get_last_credentials_required_arguments_sync() for more information about the output arguments.

If an error occurs, the function sets error and returns False.

New in version 3.16.

get_last_credentials_required_arguments_sync(cancellable)
Parameters:cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
Raises:GLib.Error
Returns:True on success, False on error
out_reason:an EDataServer.SourceCredentialsReason, why the credentials are required
out_certificate_pem:
 PEM-encoded secure connection certificate, or an empty string
out_certificate_errors:
 a bit-or of Gio.TlsCertificateFlags for secure connection certificate
out_op_error:a GLib.Error with a description of the previous credentials error
Return type:(bool, out_reason: EDataServer.SourceCredentialsReason, out_certificate_pem: str, out_certificate_errors: Gio.TlsCertificateFlags, out_op_error: GLib.Error)

Retrieves the last used arguments of the ‘credentials-required’ signal emission. If there was none emitted yet, or a corresponding ‘authenitcate’ had been emitted already, then the out_reason is set to EDataServer.SourceCredentialsReason.UNKNOWN and the value of other ‘out’ arguments is set to no values.

If an error occurs, the function sets error and returns False. The result str values should be freed with GLib.free() when no longer needed.

New in version 3.16.

get_oauth2_access_token(cancellable, callback, *user_data)
Parameters:

Asynchronously obtains the OAuth 2.0 access token for self along with its expiry in seconds from the current time (or 0 if unknown).

When the operation is finished, callback will be called. You can then call EDataServer.Source.get_oauth2_access_token_finish() to get the result of the operation.

New in version 3.8.

get_oauth2_access_token_finish(result)
Parameters:result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:GLib.Error
Returns:True on success, False on error
out_access_token:
 return location for the access token, or None
out_expires_in:return location for the token expiry, or None
Return type:(bool, out_access_token: str, out_expires_in: int)

Finishes the operation started with EDataServer.Source.get_oauth2_access_token().

Free the returned access token with GLib.free() when finished with it. If an error occurred, the function will set error and return False.

New in version 3.8.

get_oauth2_access_token_sync(cancellable)
Parameters:cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
Raises:GLib.Error
Returns:True on success, False on error
out_access_token:
 return location for the access token, or None
out_expires_in:return location for the token expiry, or None
Return type:(bool, out_access_token: str, out_expires_in: int)

Obtains the OAuth 2.0 access token for self along with its expiry in seconds from the current time (or 0 if unknown).

Free the returned access token with GLib.free() when finished with it. If an error occurs, the function will set error and return False.

New in version 3.8.

get_parent()
Returns:the UID of the parent EDataServer.Source
Return type:str

Returns the unique identifier string of the parent EDataServer.Source.

New in version 3.6.

get_remote_creatable()
Returns:whether self can create remote resources
Return type:bool

Returns whether new resources can be created on a remote server by calling EDataServer.Source.remote_create() on self.

Generally this is only True if self has an EDataServer.SourceCollection extension, which means there is an #ECollectionBackend in the D-Bus service that can handle create requests. If self does not have this capability, calls to EDataServer.Source.remote_create() will fail.

New in version 3.6.

get_remote_deletable()
Returns:whether self can delete remote resources
Return type:bool

Returns whether the resource represented by self can be deleted from a remote server by calling EDataServer.Source.remote_delete().

Generally this is only True if self is a child of an EDataServer.Source which has an EDataServer.SourceCollection extension, which means there is an #ECollectionBackend in the D-Bus service that can handle delete requests. If self does not have this capability, calls to EDataServer.Source.remote_delete() will fail.

New in version 3.6.

get_removable()
Returns:whether self is removable
Return type:bool

Returns whether the D-Bus service will allow self to be removed. If self is not writable, calls to EDataServer.Source.remove() will fail.

New in version 3.6.

get_uid()
Returns:the UID for self
Return type:str

Returns the unique identifier string for self.

New in version 3.6.

get_writable()
Returns:whether self is writable
Return type:bool

Returns whether the D-Bus service will accept changes to self. If self is not writable, calls to EDataServer.Source.write() will fail.

New in version 3.6.

has_extension(extension_name)
Parameters:extension_name (str) – an extension name
Returns:True if self has such an extension, False if not
Return type:bool

Checks whether self has an EDataServer.SourceExtension with the given name.

New in version 3.6.

hash()
Returns:a hash value for self.
Return type:int

Generates a hash value for self. This function is intended for easily hashing an EDataServer.Source to add to a GLib.HashTable or similar data structure.

New in version 3.6.

invoke_authenticate(credentials, cancellable, callback, *user_data)
Parameters:

Asynchronously calls the InvokeAuthenticate method on the server side, thus the backend knows what credentials to use to connect to its (possibly remote) data store.

When the operation is finished, callback will be called. You can then call EDataServer.Source.invoke_authenticate_finish() to get the result of the operation.

New in version 3.16.

invoke_authenticate_finish(result)
Parameters:result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:GLib.Error
Returns:True on success, False on error
Return type:bool

Finishes the operation started with EDataServer.Source.invoke_authenticate().

If an error occurs, the function sets error and returns False.

New in version 3.16.

invoke_authenticate_sync(credentials, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

True on success, False on error

Return type:

bool

Calls the InvokeAuthenticate method on the server side, thus the backend knows what credentials to use to connect to its (possibly remote) data store.

If an error occurs, the function sets error and returns False.

New in version 3.16.

invoke_credentials_required(reason, certificate_pem, certificate_errors, op_error, cancellable, callback, *user_data)
Parameters:

Asynchronously calls the InvokeCredentialsRequired method on the server side, to inform clients that credentials are required.

When the operation is finished, callback will be called. You can then call EDataServer.Source.invoke_credentials_required_finish() to get the result of the operation.

New in version 3.16.

invoke_credentials_required_finish(result)
Parameters:result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:GLib.Error
Returns:True on success, False on error
Return type:bool

Finishes the operation started with EDataServer.Source.invoke_credentials_required().

If an error occurs, the function sets error and returns False.

New in version 3.16.

invoke_credentials_required_sync(reason, certificate_pem, certificate_errors, op_error, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

True on success, False on error

Return type:

bool

Let’s the client-side know that credentials are required. The reason defines which parameters are used. The client passed the credentials with an EDataServer.Source.invoke_authenticate() call.

The EDataServer.SourceCredentialsReason.REQUIRED is used for the first credentials prompt, when the client can return credentials as stored from the previous success login.

The EDataServer.SourceCredentialsReason.REJECTED is used when the previously used credentials had been rejected by the server. That usually means that the user should be asked to provide/correct the credentials.

The EDataServer.SourceCredentialsReason.SSL_FAILED is used when a secured connection failed due to some server-side certificate issues.

The EDataServer.SourceCredentialsReason.ERROR is used when the server returned an error. It is not possible to connect to it at the moment usually.

If an error occurs, the function sets error and returns False.

New in version 3.16.

lookup_password(cancellable, callback, *user_data)
Parameters:

Asynchronously looks up a password for self. Both the default and session keyrings are queried. This operation does not rely on the registry service and therefore works for any EDataServer.Source – registered or “scratch”.

When the operation is finished, callback will be called. You can then call EDataServer.Source.lookup_password_finish() to get the result of the operation.

New in version 3.12.

lookup_password_finish(result)
Parameters:result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:GLib.Error
Returns:True on success, False on error
out_password:return location for the password, or None
Return type:(bool, out_password: str)

Finishes the operation started with EDataServer.Source.lookup_password().

Note the boolean return value indicates whether the lookup operation itself completed successfully, not whether a password was found. If no password was found, the function will set out_password to None but still return True. If an error occurs, the function sets error and returns False.

New in version 3.12.

lookup_password_sync(cancellable)
Parameters:cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
Raises:GLib.Error
Returns:True on success, False on error
out_password:return location for the password, or None
Return type:(bool, out_password: str)

Looks up a password for self. Both the default and session keyrings are queried. This operation does not rely on the registry service and therefore works for any EDataServer.Source – registered or “scratch”.

Note the boolean return value indicates whether the lookup operation itself completed successfully, not whether a password was found. If no password was found, the function will set out_password to None but still return True. If an error occurs, the function sets error and returns False.

New in version 3.12.

mail_signature_load(io_priority, cancellable, callback, *user_data)
Parameters:

Asynchronously loads a signature from the signature file for self, which is given by EDataServer.SourceMailSignature.get_file().

If the signature file is executable, it will be executed and its output captured as the email signature content. If the signature file is not executable, the email signature content is read directly from the file.

When the operation is finished, callback will be called. You can then call EDataServer.Source.mail_signature_load_finish() to get the result of the operation.

New in version 3.6.

mail_signature_load_finish(result)
Parameters:result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:GLib.Error
Returns:True on success, False on failure
contents:return location for the signature content
length:return location for the length of the signature content, or None if the length is not needed
Return type:(bool, contents: str, length: int)

Finishes an operation started with EDataServer.Source.mail_signature_load(). The signature file contents are placed in contents, and length is set to the size of the contents string. The contents string should be freed with GLib.free() when no longer needed.

New in version 3.6.

mail_signature_load_sync(cancellable)
Parameters:cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
Raises:GLib.Error
Returns:True on success, False on failure
contents:return location for the signature content
length:return location for the length of the signature content, or None if the length is not needed
Return type:(bool, contents: str, length: int)

Loads a signature from the signature file for self, which is given by EDataServer.SourceMailSignature.get_file(). The signature contents are placed in contents, and length is set to the size of the contents string. The contents string should be freed with GLib.free() when no longer needed.

If the signature file is executable, it will be executed and its output captured as the email signature content. If the signature file is not executable, the email signature content is read directly from the file.

New in version 3.6.

mail_signature_replace(contents, length, io_priority, cancellable, callback, *user_data)
Parameters:

Asynchrously replaces the signature file for self with the given contents of length bytes. The signature file for self is given by EDataServer.SourceMailSignature.get_file().

When the operation is finished, callback will be called. You can then call EDataServer.Source.mail_signature_replace_finish() to get the result of the operation.

New in version 3.6.

mail_signature_replace_finish(result)
Parameters:result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:GLib.Error
Returns:True on success, False on failure
Return type:bool

Finishes an operation started with EDataServer.Source.mail_signature_replace().

New in version 3.6.

mail_signature_replace_sync(contents, length, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

True on success, False on failure

Return type:

bool

Replaces the signature file for self with the given contents of length bytes. The signature file for self is given by EDataServer.SourceMailSignature.get_file().

New in version 3.6.

Parameters:

Asynchronously replaces the signature file for self with a symbolic link to symlink_target, which should be an executable file that prints a mail signature to standard output. The signature file for self is given by EDataServer.SourceMailSignature.get_file().

When the operation is finished, callback will be called. You can then call EDataServer.Source.mail_signature_symlink_finish() to get the result of the operation.

New in version 3.6.

Parameters:result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:GLib.Error
Returns:True on success, False on failure
Return type:bool

Finishes an operation started with EDataServer.Source.mail_signature_symlink().

New in version 3.6.

Parameters:
Raises:

GLib.Error

Returns:

True on success, False on failure

Return type:

bool

Replaces the signature file for self with a symbolic link to symlink_target, which should be an executable file that prints a mail signature to standard output. The signature file for self is given by EDataServer.SourceMailSignature.get_file().

New in version 3.6.

proxy_lookup(uri, cancellable, callback, *user_data)
Parameters:

Asynchronously determines what proxy, if any, to use to connect to uri. See EDataServer.Source.proxy_lookup_sync() for more details.

When the operation is finished, callback will be called. You can then call EDataServer.Source.proxy_lookup_finish() to get the result of the operation.

New in version 3.12.

proxy_lookup_finish(result)
Parameters:result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:GLib.Error
Returns:a None-terminated array of proxy URIs, or None
Return type:[str]

Finishes the operation started with EDataServer.Source.proxy_lookup().

Free the returned proxy URIs with GLib.strfreev() when finished with them.

New in version 3.12.

proxy_lookup_sync(uri, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

a None-terminated array of proxy URIs, or None

Return type:

[str]

Looks into self’s EDataServer.SourceProxy extension to determine what proxy, if any, to use to connect to uri. The returned proxy URIs are of the same form described by Gio.ProxyResolver.lookup().

The proxy extension’s EDataServer.SourceProxy :method controls how proxy URIs are determined:

When using EDataServer.ProxyMethod.DEFAULT, the function will defer to the Gio.ProxyResolver returned by Gio.ProxyResolver.get_default().

When using EDataServer.ProxyMethod.MANUAL, the function will configure a Gio.SimpleProxyResolver from the HTTP, HTTPS, FTP and SOCKS properties, as well as EDataServer.SourceProxy :ignore-hosts.

When using EDataServer.ProxyMethod.AUTO, the function will execute a proxy auto-config (PAC) file at EDataServer.SourceProxy :autoconfig-url.

When using EDataServer.ProxyMethod.NONE, the function will only return direct://.

If self does not have an EDataServer.SourceProxy extension, the function sets error to Gio.IOErrorEnum.NOT_SUPPORTED and returns None.

Free the returned proxy URIs with GLib.strfreev() when finished with them.

New in version 3.12.

ref_dbus_object()
Returns:the Gio.DBusObject for self, or None
Return type:Gio.DBusObject

Returns the Gio.DBusObject that was passed to EDataServer.Source.new().

The returned Gio.DBusObject is referenced for thread-safety and must be unreferenced with GObject.Object.unref() when finished with it.

New in version 3.6.

ref_main_context()
Returns:a GLib.MainContext
Return type:GLib.MainContext

Returns the GLib.MainContext on which event sources for self are to be attached.

The returned GLib.MainContext is referenced for thread-safety and must be unreferenced with GLib.MainContext.unref() when finished with it.

New in version 3.6.

refresh_add_timeout(context, callback, *user_data)
Parameters:
Returns:

a refresh timeout ID

Return type:

int

This is a simple way to schedule a periodic data source refresh.

Adds a timeout GLib.Source to context and handles all the bookkeeping if self’s refresh EDataServer.SourceRefresh :enabled state or its refresh EDataServer.SourceRefresh :interval-minutes value changes. The callback is expected to dispatch an asynchronous job to connect to and fetch updates from a remote server.

The returned ID can be passed to EDataServer.Source.refresh_remove_timeout() to remove the timeout from context. Note the ID is a private handle and cannot be passed to GLib.Source.remove().

New in version 3.6.

refresh_force_timeout()

For all timeouts added with EDataServer.Source.refresh_add_timeout(), invokes the EDataServer.SourceRefreshFunc callback immediately and then, if the refresh EDataServer.SourceRefresh :enabled state is True, reschedules the timeout.

This function is called automatically when the EDataServer.Source switches from disabled to enabled, but can also be useful when a network connection becomes available or when waking up from hibernation or suspend.

New in version 3.6.

refresh_remove_timeout(refresh_timeout_id)
Parameters:refresh_timeout_id (int) – a refresh timeout ID
Returns:True if the timeout was found and removed
Return type:bool

Removes a timeout GLib.Source added by EDataServer.Source.refresh_add_timeout().

New in version 3.6.

refresh_remove_timeouts_by_data(user_data)
Parameters:user_data (object or None) – user data to match against timeout callbacks
Returns:the number of timeouts found and removed
Return type:int

Removes all timeout GLib.Source’s added by EDataServer.Source.refresh_add_timeout() whose callback data pointer matches user_data.

New in version 3.6.

remote_create(scratch_source, cancellable, callback, *user_data)
Parameters:

Asynchronously creates a new remote resource by picking out relevant details from scratch_source. The scratch_source must be an EDataServer.Source with no Gio.DBusObject. The self must be EDataServer.Source :remote-creatable.

The details required to create the resource vary by #ECollectionBackend, but in most cases the scratch_source need only define the resource type (address book, calendar, etc.), a display name for the resource, and possibly a server-side path or ID for the resource.

When the operation is finished, callback will be called. You can then call EDataServer.Source.remote_create_finish() to get the result of the operation.

New in version 3.6.

remote_create_finish(result)
Parameters:result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:GLib.Error
Returns:True on success, False on error
Return type:bool

Finishes the operation started with EDataServer.Source.remote_create(). If an error occurred, the function will set error and return False.

New in version 3.6.

remote_create_sync(scratch_source, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

True on success, False on error

Return type:

bool

Creates a new remote resource by picking out relevant details from scratch_source. The scratch_source must be an EDataServer.Source with no Gio.DBusObject. The self must be EDataServer.Source :remote-creatable.

The details required to create the resource vary by #ECollectionBackend, but in most cases the scratch_source need only define the resource type (address book, calendar, etc.), a display name for the resource, and possibly a server-side path or ID for the resource.

If an error occurs, the function will set error and return False.

New in version 3.6.

remote_delete(cancellable, callback, *user_data)
Parameters:

Asynchronously deletes the resource represented by self from a remote server. The self must be EDataServer.Source :remote-deletable. This will also delete the key file for self and broadcast its removal to all clients, similar to EDataServer.Source.remove().

When the operation is finished, callback will be called. You can then call EDataServer.Source.remote_delete_finish() to get the result of the operation.

New in version 3.6.

remote_delete_finish(result)
Parameters:result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:GLib.Error
Returns:True on success, False on error
Return type:bool

Finishes the operation started with EDataServer.Source.remote_delete(). If an error occurred, the function will set error and return False.

New in version 3.6.

remote_delete_sync(cancellable)
Parameters:cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
Raises:GLib.Error
Returns:True on success, False on error
Return type:bool

Deletes the resource represented by self from a remote server. The self must be EDataServer.Source :remote-deletable. This will also delete the key file for self and broadcast its removal to all clients, similar to EDataServer.Source.remove_sync().

If an error occurs, the function will set error and return False.

New in version 3.6.

remove(cancellable, callback, *user_data)
Parameters:

Asynchronously requests the D-Bus service to delete the key files for self and all of its descendants and broadcast their removal to all clients. The self must be EDataServer.Source :removable.

When the operation is finished, callback will be called. You can then call EDataServer.Source.remove_finish() to get the result of the operation.

New in version 3.6.

remove_finish(result)
Parameters:result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:GLib.Error
Returns:True on success, False of failure
Return type:bool

Finishes the operation started with EDataServer.Source.remove(). If an error occurred, the function will set error and return False.

New in version 3.6.

remove_sync(cancellable)
Parameters:cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
Raises:GLib.Error
Returns:True on success, False on error
Return type:bool

Requests the D-Bus service to delete the key files for self and all of its descendants and broadcast their removal to all clients. The self must be EDataServer.Source :removable.

If an error occurs, the functon will set error and return False.

New in version 3.6.

set_connection_status(connection_status)
Parameters:connection_status (EDataServer.SourceConnectionStatus) – one of the EDataServer.SourceConnectionStatus

Set’s current connection status of the self.

New in version 3.16.

set_display_name(display_name)
Parameters:display_name (str) – a display name

Sets the display name for self. The display_name argument must be a valid UTF-8 string. Use the display name to represent the EDataServer.Source in a user interface.

The internal copy of display_name is automatically stripped of leading and trailing whitespace.

New in version 3.6.

set_enabled(enabled)
Parameters:enabled (bool) – whether to enable self

Enables or disables self.

An application should try to honor this setting if at all possible, even if it does not provide a way to change the setting through its user interface. Disabled data sources should generally be hidden.

New in version 3.6.

set_parent(parent)
Parameters:parent (str or None) – the UID of the parent EDataServer.Source, or None

Identifies the parent of self by its unique identifier string. This can only be set prior to adding self to an EDataServer.SourceRegistry.

The internal copy of EDataServer.Source :parent is automatically stripped of leading and trailing whitespace. If the resulting string is empty, None is set instead.

New in version 3.6.

store_password(password, permanently, cancellable, callback, *user_data)
Parameters:

Asynchronously stores a password for self. This operation does not rely on the registry service and therefore works for any EDataServer.Source – registered or “scratch”.

If permanently is True, the password is stored in the default keyring. Otherwise the password is stored in the memory-only session keyring. If an error occurs, the function sets error and returns False.

When the operation is finished, callback will be called. You can then call EDataServer.Source.store_password_finish() to get the result of the operation.

New in version 3.12.

store_password_finish(result)
Parameters:result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:GLib.Error
Returns:True on success, False on error
Return type:bool

Finishes the operation started with EDataServer.Source.store_password().

New in version 3.12.

store_password_sync(password, permanently, cancellable)
Parameters:
Raises:

GLib.Error

Returns:

True on success, False on error

Return type:

bool

Stores a password for self. This operation does not rely on the registry service and therefore works for any EDataServer.Source – registered or “scratch”.

If permanently is True, the password is stored in the default keyring. Otherwise the password is stored in the memory-only session keyring. If an error occurs, the function sets error and returns False.

New in version 3.12.

to_string(length)
Parameters:length (int or None) – return location for the length of the returned string, or None
Returns:a newly-allocated string
Return type:str

Outputs the current contents of self as a key file string. Free the returned string with GLib.free().

New in version 3.6.

unset_last_credentials_required_arguments(cancellable, callback, *user_data)
Parameters:

Asynchronously calls the UnsetLastCredentialsRequiredArguments method on the server side, to unset the last values used for the ‘credentials-required’ signal.

When the operation is finished, callback will be called. You can then call EDataServer.Source.unset_last_credentials_required_arguments_finish() to get the result of the operation.

New in version 3.18.

unset_last_credentials_required_arguments_finish(result)
Parameters:result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:GLib.Error
Returns:True on success, False on error
Return type:bool

Finishes the operation started with EDataServer.Source.unset_last_credentials_required_arguments().

If an error occurs, the function sets error and returns False.

New in version 3.18.

unset_last_credentials_required_arguments_sync(cancellable)
Parameters:cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
Raises:GLib.Error
Returns:True on success, False on error
Return type:bool

Unsets the last used arguments of the ‘credentials-required’ signal emission.

If an error occurs, the function sets error and returns False.

New in version 3.18.

write(cancellable, callback, *user_data)
Parameters:

Asynchronously submits the current contents of self to the D-Bus service to be written to disk and broadcast to other clients. The self must be EDataServer.Source :writable.

When the operation is finished, callback will be called. You can then call EDataServer.Source.write_finish() to get the result of the operation.

New in version 3.6.

write_finish(result)
Parameters:result (Gio.AsyncResult) – a Gio.AsyncResult
Raises:GLib.Error
Returns:True on success, False on error
Return type:bool

Finishes the operation started with EDataServer.Source.write(). If an error occurred, the function will set error and return False.

New in version 3.6.

write_sync(cancellable)
Parameters:cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
Raises:GLib.Error
Returns:True on success, False on error
Return type:bool

Submits the current contents of self to the D-Bus service to be written to disk and broadcast to other clients. The self must be EDataServer.Source :writable.

If an error occurs, the functon will set error and return False.

New in version 3.6.

do_authenticate(credentials) virtual
Parameters:credentials (EDataServer.NamedParameters) –
do_changed() virtual

Emits the EDataServer.Source ::changed signal from an idle callback in source’s EDataServer.Source :main-context.

This function is primarily intended for use by EDataServer.SourceExtension when emitting a GObject.Object ::notify signal on one of its properties.

New in version 3.6.

do_credentials_required(reason, certificate_pem, certificate_errors, op_error) virtual
Parameters:
do_get_oauth2_access_token(cancellable, callback, *user_data) virtual
Parameters:

Asynchronously obtains the OAuth 2.0 access token for source along with its expiry in seconds from the current time (or 0 if unknown).

When the operation is finished, callback will be called. You can then call EDataServer.Source.get_oauth2_access_token_finish() to get the result of the operation.

New in version 3.8.

do_get_oauth2_access_token_finish(result) virtual
Parameters:result (Gio.AsyncResult) – a Gio.AsyncResult
Returns:True on success, False on error
out_access_token:
 return location for the access token, or None
out_expires_in:return location for the token expiry, or None
Return type:(bool, out_access_token: str, out_expires_in: int)

Finishes the operation started with EDataServer.Source.get_oauth2_access_token().

Free the returned access token with GLib.free() when finished with it. If an error occurred, the function will set error and return False.

New in version 3.8.

do_get_oauth2_access_token_sync(cancellable) virtual
Parameters:cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
Returns:True on success, False on error
out_access_token:
 return location for the access token, or None
out_expires_in:return location for the token expiry, or None
Return type:(bool, out_access_token: str, out_expires_in: int)

Obtains the OAuth 2.0 access token for source along with its expiry in seconds from the current time (or 0 if unknown).

Free the returned access token with GLib.free() when finished with it. If an error occurs, the function will set error and return False.

New in version 3.8.

do_invoke_authenticate_impl(dbus_source, arg_credentials, cancellable) virtual
Parameters:
Return type:

bool

do_invoke_credentials_required_impl(dbus_source, arg_reason, arg_certificate_pem, arg_certificate_errors, arg_dbus_error_name, arg_dbus_error_message, cancellable) virtual
Parameters:
  • dbus_source (object or None) –
  • arg_reason (str) –
  • arg_certificate_pem (str) –
  • arg_certificate_errors (str) –
  • arg_dbus_error_name (str) –
  • arg_dbus_error_message (str) –
  • cancellable (Gio.Cancellable or None) –
Return type:

bool

do_remote_create(scratch_source, cancellable, callback, *user_data) virtual
Parameters:

Asynchronously creates a new remote resource by picking out relevant details from scratch_source. The scratch_source must be an EDataServer.Source with no Gio.DBusObject. The source must be EDataServer.Source :remote-creatable.

The details required to create the resource vary by #ECollectionBackend, but in most cases the scratch_source need only define the resource type (address book, calendar, etc.), a display name for the resource, and possibly a server-side path or ID for the resource.

When the operation is finished, callback will be called. You can then call EDataServer.Source.remote_create_finish() to get the result of the operation.

New in version 3.6.

do_remote_create_finish(result) virtual
Parameters:result (Gio.AsyncResult) – a Gio.AsyncResult
Returns:True on success, False on error
Return type:bool

Finishes the operation started with EDataServer.Source.remote_create(). If an error occurred, the function will set error and return False.

New in version 3.6.

do_remote_create_sync(scratch_source, cancellable) virtual
Parameters:
Returns:

True on success, False on error

Return type:

bool

Creates a new remote resource by picking out relevant details from scratch_source. The scratch_source must be an EDataServer.Source with no Gio.DBusObject. The source must be EDataServer.Source :remote-creatable.

The details required to create the resource vary by #ECollectionBackend, but in most cases the scratch_source need only define the resource type (address book, calendar, etc.), a display name for the resource, and possibly a server-side path or ID for the resource.

If an error occurs, the function will set error and return False.

New in version 3.6.

do_remote_delete(cancellable, callback, *user_data) virtual
Parameters:

Asynchronously deletes the resource represented by source from a remote server. The source must be EDataServer.Source :remote-deletable. This will also delete the key file for source and broadcast its removal to all clients, similar to EDataServer.Source.remove().

When the operation is finished, callback will be called. You can then call EDataServer.Source.remote_delete_finish() to get the result of the operation.

New in version 3.6.

do_remote_delete_finish(result) virtual
Parameters:result (Gio.AsyncResult) – a Gio.AsyncResult
Returns:True on success, False on error
Return type:bool

Finishes the operation started with EDataServer.Source.remote_delete(). If an error occurred, the function will set error and return False.

New in version 3.6.

do_remote_delete_sync(cancellable) virtual
Parameters:cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
Returns:True on success, False on error
Return type:bool

Deletes the resource represented by source from a remote server. The source must be EDataServer.Source :remote-deletable. This will also delete the key file for source and broadcast its removal to all clients, similar to EDataServer.Source.remove_sync().

If an error occurs, the function will set error and return False.

New in version 3.6.

do_remove(cancellable, callback, *user_data) virtual
Parameters:

Asynchronously requests the D-Bus service to delete the key files for source and all of its descendants and broadcast their removal to all clients. The source must be EDataServer.Source :removable.

When the operation is finished, callback will be called. You can then call EDataServer.Source.remove_finish() to get the result of the operation.

New in version 3.6.

do_remove_finish(result) virtual
Parameters:result (Gio.AsyncResult) – a Gio.AsyncResult
Returns:True on success, False of failure
Return type:bool

Finishes the operation started with EDataServer.Source.remove(). If an error occurred, the function will set error and return False.

New in version 3.6.

do_remove_sync(cancellable) virtual
Parameters:cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
Returns:True on success, False on error
Return type:bool

Requests the D-Bus service to delete the key files for source and all of its descendants and broadcast their removal to all clients. The source must be EDataServer.Source :removable.

If an error occurs, the functon will set error and return False.

New in version 3.6.

do_unset_last_credentials_required_arguments_impl(cancellable) virtual
Parameters:cancellable (Gio.Cancellable or None) –
Return type:bool
do_write(cancellable, callback, *user_data) virtual
Parameters:

Asynchronously submits the current contents of source to the D-Bus service to be written to disk and broadcast to other clients. The source must be EDataServer.Source :writable.

When the operation is finished, callback will be called. You can then call EDataServer.Source.write_finish() to get the result of the operation.

New in version 3.6.

do_write_finish(result) virtual
Parameters:result (Gio.AsyncResult) – a Gio.AsyncResult
Returns:True on success, False on error
Return type:bool

Finishes the operation started with EDataServer.Source.write(). If an error occurred, the function will set error and return False.

New in version 3.6.

do_write_sync(cancellable) virtual
Parameters:cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, or None
Returns:True on success, False on error
Return type:bool

Submits the current contents of source to the D-Bus service to be written to disk and broadcast to other clients. The source must be EDataServer.Source :writable.

If an error occurs, the functon will set error and return False.

New in version 3.6.

Signal Details

EDataServer.Source.signals.authenticate(source, credentials)
Signal Name:

authenticate

Flags:

RUN_LAST, NO_RECURSE

Parameters:

Let’s the backend know provided credentials to use to login to (possibly remote) data store.

EDataServer.Source.signals.changed(source)
Signal Name:changed
Flags:RUN_LAST, NO_RECURSE
Parameters:source (EDataServer.Source) – The object which received the signal

The ::changed signal is emitted when a property in source or one of its extension objects changes. A common use for this signal is to notify a #GtkTreeModel containing data collected from EDataServer.Source s that it needs to update a row.

EDataServer.Source.signals.credentials_required(source, reason, certificate_pem, certificate_errors, error)
Signal Name:

credentials-required

Flags:

RUN_LAST, NO_RECURSE

Parameters:

The ::credentials-required signal is emitted when the source requires credentials to connect to (possibly remote) data store. The credentials can be passed to the backend using EDataServer.Source.invoke_authenticate() function.

Property Details

EDataServer.Source.props.connection_status
Name:connection-status
Type:EDataServer.SourceConnectionStatus
Default Value:EDataServer.SourceConnectionStatus.DISCONNECTED
Flags:READABLE

Connection status of the source

EDataServer.Source.props.display_name
Name:display-name
Type:str
Default Value:'Unnamed'
Flags:READABLE, WRITABLE, CONSTRUCT, EXPLICIT_NOTIFY

The human-readable name of the data source

EDataServer.Source.props.enabled
Name:enabled
Type:bool
Default Value:True
Flags:READABLE, WRITABLE, CONSTRUCT, EXPLICIT_NOTIFY

Whether the data source is enabled

EDataServer.Source.props.main_context
Name:main-context
Type:GLib.MainContext
Default Value:None
Flags:READABLE, WRITABLE, CONSTRUCT_ONLY

The main loop context on which to attach event sources

EDataServer.Source.props.parent
Name:parent
Type:str
Default Value:None
Flags:READABLE, WRITABLE, EXPLICIT_NOTIFY

The unique identity of the parent data source

EDataServer.Source.props.remote_creatable
Name:remote-creatable
Type:bool
Default Value:False
Flags:READABLE

Whether the data source can create remote resources

EDataServer.Source.props.remote_deletable
Name:remote-deletable
Type:bool
Default Value:False
Flags:READABLE

Whether the data source can delete remote resources

EDataServer.Source.props.removable
Name:removable
Type:bool
Default Value:False
Flags:READABLE

Whether the data source is removable

EDataServer.Source.props.uid
Name:uid
Type:str
Default Value:None
Flags:READABLE, WRITABLE, CONSTRUCT_ONLY

The unique identity of the data source

EDataServer.Source.props.writable
Name:writable
Type:bool
Default Value:False
Flags:READABLE

Whether the data source is writable