GI.Secret.Objects.Item

A secret item

Item represents a secret item stored in the Secret Service.

Each item has a value, represented by a [structvalue], which can be retrieved by [methoditem.get_secret] or set by [methoditem.set_secret]. The item is only available when the item is not locked.

Items can be locked or unlocked using the [methodservice.lock] or [methodservice.unlock] functions. The Secret Service may not be able to unlock individual items, and may unlock an entire collection when a single item is unlocked.

Each item has a set of attributes, which are used to locate the item later. These are not stored or transferred in a secure manner. Each attribute has a string name and a string value. Use [methodservice.search] to search for items based on their attributes, and [methoditem.set_attributes] to change the attributes associated with an item.

Items can be created with Item.create or [methodservice.store].

Exported types

newtype Item

Memory-managed wrapper type.

Constructors

Item (ManagedPtr Item)

Instances

Eq Item

Defined in GI.Secret.Objects.Item

Methods

(==) :: Item -> Item -> Bool

(/=) :: Item -> Item -> Bool

GObject Item

Defined in GI.Secret.Objects.Item

ManagedPtrNewtype Item

Defined in GI.Secret.Objects.Item

Methods

toManagedPtr :: Item -> ManagedPtr Item

TypedObject Item

Defined in GI.Secret.Objects.Item

Methods

glibType :: IO GType

HasParentTypes Item

Defined in GI.Secret.Objects.Item

IsGValue (Maybe Item)

Convert Item to and from GValue. See toGValue and fromGValue.

Defined in GI.Secret.Objects.Item

Methods

gvalueGType_ :: IO GType

gvalueSet_ :: Ptr GValue -> Maybe Item -> IO ()

gvalueGet_ :: Ptr GValue -> IO (Maybe Item)

type ParentTypes Item

Defined in GI.Secret.Objects.Item

type ParentTypes Item = '[DBusProxy, Object, AsyncInitable, DBusInterface, Initable, Retrievable]

class (GObject o, IsDescendantOf Item o) => IsItem o

Type class for types which can be safely cast to Item, for instance with toItem.

Instances

(GObject o, IsDescendantOf Item o) => IsItem o

Defined in GI.Secret.Objects.Item

toItem :: (MonadIO m, IsItem o) => o -> m Item

Cast to Item, for types for which this is known to be safe. For general casts, use castTo.

Methods

Click to display all available methods, including inherited ones

Methods

bindProperty, bindPropertyFull, call, callFinish, callSync, callWithUnixFdList, callWithUnixFdListFinish, callWithUnixFdListSync, delete, deleteFinish, deleteSync, forceFloating, freezeNotify, getv, init, initAsync, initFinish, isFloating, loadSecret, loadSecretFinish, loadSecretSync, notify, notifyByPspec, ref, refSink, refresh, retrieveSecret, retrieveSecretFinish, retrieveSecretSync, runDispose, stealData, stealQdata, thawNotify, unref, watchClosure.

Getters

getAttributes, getCachedProperty, getCachedPropertyNames, getConnection, getCreated, getData, getDefaultTimeout, getFlags, getInfo, getInterfaceInfo, getInterfaceName, getLabel, getLocked, getModified, getName, getNameOwner, getObject, getObjectPath, getProperty, getQdata, getSchemaName, getSecret, getService.

Setters

setAttributes, setAttributesFinish, setAttributesSync, setCachedProperty, setData, setDataFull, setDefaultTimeout, setInterfaceInfo, setLabel, setLabelFinish, setLabelSync, setObject, setProperty, setSecret, setSecretFinish, setSecretSync.

create

itemCreate

Arguments

:: (HasCallStack, MonadIO m, IsCollection a, IsCancellable b)

=> a

collection: a secret collection to create this item in

-> Maybe Schema

schema: the schema for the attributes

-> Map Text Text

attributes: attributes for the new item

-> Text

label: label for the new item

-> Value

value: secret value for the new item

-> [ItemCreateFlags]

flags: flags for the creation of the new item

-> Maybe b

cancellable: optional cancellation object

-> Maybe AsyncReadyCallback

callback: called when the operation completes

-> m ()

Create a new item in the secret service.

If the flags contains ItemCreateFlagsReplace, then the secret service will search for an item matching the attributes, and update that item instead of creating a new one.

This method may block indefinitely and should not be used in user interface threads. The secret service may prompt the user. [methodservice.prompt] will be used to handle any prompts that are required.

createFinish

itemCreateFinish

Arguments

:: (HasCallStack, MonadIO m, IsAsyncResult a)

=> a

result: the asynchronous result passed to the callback

-> m Item

Returns: the new item, which should be unreferenced with objectUnref (Can throw GError)

Finish operation to create a new item in the secret service.

createSync

itemCreateSync

Arguments

:: (HasCallStack, MonadIO m, IsCollection a, IsCancellable b)

=> a

collection: a secret collection to create this item in

-> Maybe Schema

schema: the schema for the attributes

-> Map Text Text

attributes: attributes for the new item

-> Text

label: label for the new item

-> Value

value: secret value for the new item

-> [ItemCreateFlags]

flags: flags for the creation of the new item

-> Maybe b

cancellable: optional cancellation object

-> m Item

Returns: the new item, which should be unreferenced with objectUnref (Can throw GError)

Create a new item in the secret service.

If the flags contains ItemCreateFlagsReplace, then the secret service will search for an item matching the attributes, and update that item instead of creating a new one.

This method may block indefinitely and should not be used in user interface threads. The secret service may prompt the user. [methodservice.prompt] will be used to handle any prompts that are required.

delete

itemDelete

Arguments

:: (HasCallStack, MonadIO m, IsItem a, IsCancellable b)

=> a

self: an item

-> Maybe b

cancellable: optional cancellation object

-> Maybe AsyncReadyCallback

callback: called when the operation completes

-> m ()

Delete this item.

This method returns immediately and completes asynchronously. The secret service may prompt the user. [methodservice.prompt] will be used to handle any prompts that show up.

deleteFinish

itemDeleteFinish

Arguments

:: (HasCallStack, MonadIO m, IsItem a, IsAsyncResult b)

=> a

self: an item

-> b

result: asynchronous result passed to the callback

-> m ()

(Can throw GError)

Complete asynchronous operation to delete the secret item.

deleteSync

itemDeleteSync

Arguments

:: (HasCallStack, MonadIO m, IsItem a, IsCancellable b)

=> a

self: an item

-> Maybe b

cancellable: optional cancellation object

-> m ()

(Can throw GError)

Delete this secret item.

This method may block indefinitely and should not be used in user interface threads. The secret service may prompt the user. [methodservice.prompt] will be used to handle any prompts that show up.

getAttributes

itemGetAttributes

Arguments

:: (HasCallStack, MonadIO m, IsItem a)

=> a

self: an item

-> m (Map Text Text)

Returns: a new reference to the attributes, which should not be modified, and released with [funcgLib.HashTable.unref]

Set the attributes of this item.

The attributes are a mapping of string keys to string values. Attributes are used to search for items. Attributes are not stored or transferred securely by the secret service.

Do not modify the attributes returned by this method. Use [methoditem.set_attributes] instead.

getCreated

itemGetCreated

Arguments

:: (HasCallStack, MonadIO m, IsItem a)

=> a

self: an item

-> m Word64

Returns: the created date and time

Get the created date and time of the item.

The return value is the number of seconds since the unix epoch, January 1st 1970.

getFlags

itemGetFlags

Arguments

:: (HasCallStack, MonadIO m, IsItem a)

=> a

self: the secret item proxy

-> m [ItemFlags]

Returns: the flags for features initialized

Get the flags representing what features of the Item proxy have been initialized.

Use [methoditem.load_secret] to initialize further features and change the flags.

getLabel

itemGetLabel

Arguments

:: (HasCallStack, MonadIO m, IsItem a)

=> a

self: an item

-> m Text

Returns: the label, which should be freed with free

Get the label of this item.

getLocked

itemGetLocked

Arguments

:: (HasCallStack, MonadIO m, IsItem a)

=> a

self: an item

-> m Bool

Returns: whether the item is locked or not

Get whether the item is locked or not.

Depending on the secret service an item may not be able to be locked independently from the collection that it is in.

getModified

itemGetModified

Arguments

:: (HasCallStack, MonadIO m, IsItem a)

=> a

self: an item

-> m Word64

Returns: the modified date and time

Get the modified date and time of the item.

The return value is the number of seconds since the unix epoch, January 1st 1970.

getSchemaName

itemGetSchemaName

Arguments

:: (HasCallStack, MonadIO m, IsItem a)

=> a

self: an item

-> m (Maybe Text)

Returns: the schema name

Gets the name of the schema that this item was stored with. This is also available at the xdg:schema attribute.

getSecret

itemGetSecret

Arguments

:: (HasCallStack, MonadIO m, IsItem a)

=> a

self: an item

-> m (Maybe Value)

Returns: the secret value which should be released with [methodvalue.unref], or Nothing

Get the secret value of this item.

If this item is locked or the secret has not yet been loaded then this will return Nothing.

To load the secret call the [methoditem.load_secret] method.

getService

itemGetService

Arguments

:: (HasCallStack, MonadIO m, IsItem a)

=> a

self: an item

-> m Service

Returns: the Secret Service object

Get the Secret Service object that this item was created with.

loadSecret

itemLoadSecret

Arguments

:: (HasCallStack, MonadIO m, IsItem a, IsCancellable b)

=> a

self: an item proxy

-> Maybe b

cancellable: optional cancellation object

-> Maybe AsyncReadyCallback

callback: called when the operation completes

-> m ()

Load the secret value of this item.

Each item has a single secret which might be a password or some other secret binary value.

This function will fail if the secret item is locked.

This function returns immediately and completes asynchronously.

loadSecretFinish

itemLoadSecretFinish

Arguments

:: (HasCallStack, MonadIO m, IsItem a, IsAsyncResult b)

=> a

self: an item proxy

-> b

result: asynchronous result passed to callback

-> m ()

(Can throw GError)

Complete asynchronous operation to load the secret value of this item.

The newly loaded secret value can be accessed by calling [methoditem.get_secret].

loadSecretSync

itemLoadSecretSync

Arguments

:: (HasCallStack, MonadIO m, IsItem a, IsCancellable b)

=> a

self: an item

-> Maybe b

cancellable: optional cancellation object

-> m ()

(Can throw GError)

Load the secret value of this item.

Each item has a single secret which might be a password or some other secret binary value.

This function may block indefinitely. Use the asynchronous version in user interface threads.

loadSecrets

itemLoadSecrets

Arguments

:: (HasCallStack, MonadIO m, IsItem a, IsCancellable b)

=> [a]

items: the items to retrieve secrets for

-> Maybe b

cancellable: optional cancellation object

-> Maybe AsyncReadyCallback

callback: called when the operation completes

-> m ()

Load the secret values for a secret item stored in the service.

The items must all have the same [propertyitem:service] property.

This function returns immediately and completes asynchronously.

loadSecretsFinish

itemLoadSecretsFinish

Arguments

:: (HasCallStack, MonadIO m, IsAsyncResult a)

=> a

result: asynchronous result passed to callback

-> m ()

(Can throw GError)

Complete asynchronous operation to load the secret values for secret items stored in the service.

Items that are locked will not have their secrets loaded.

loadSecretsSync

itemLoadSecretsSync

Arguments

:: (HasCallStack, MonadIO m, IsItem a, IsCancellable b)

=> [a]

items: the items to retrieve secrets for

-> Maybe b

cancellable: optional cancellation object

-> m ()

(Can throw GError)

Load the secret values for a secret item stored in the service.

The items must all have the same [propertyitem:service] property.

This method may block indefinitely and should not be used in user interface threads.

Items that are locked will not have their secrets loaded.

refresh

itemRefresh

Arguments

:: (HasCallStack, MonadIO m, IsItem a)

=> a

self: the collection

-> m ()

Refresh the properties on this item.

This fires off a request to refresh, and the properties will be updated later.

Calling this method is not normally necessary, as the secret service will notify the client when properties change.

setAttributes

itemSetAttributes

Arguments

:: (HasCallStack, MonadIO m, IsItem a, IsCancellable b)

=> a

self: an item

-> Maybe Schema

schema: the schema for the attributes

-> Map Text Text

attributes: a new set of attributes

-> Maybe b

cancellable: optional cancellation object

-> Maybe AsyncReadyCallback

callback: called when the asynchronous operation completes

-> m ()

Set the attributes of this item.

The attributes are a mapping of string keys to string values. Attributes are used to search for items. Attributes are not stored or transferred securely by the secret service.

This function returns immediately and completes asynchronously.

setAttributesFinish

itemSetAttributesFinish

Arguments

:: (HasCallStack, MonadIO m, IsItem a, IsAsyncResult b)

=> a

self: an item

-> b

result: asynchronous result passed to the callback

-> m ()

(Can throw GError)

Complete operation to set the attributes of this item.

setAttributesSync

itemSetAttributesSync

Arguments

:: (HasCallStack, MonadIO m, IsItem a, IsCancellable b)

=> a

self: an item

-> Maybe Schema

schema: the schema for the attributes

-> Map Text Text

attributes: a new set of attributes

-> Maybe b

cancellable: optional cancellation object

-> m ()

(Can throw GError)

Set the attributes of this item.

The attributes are a mapping of string keys to string values. Attributes are used to search for items. Attributes are not stored or transferred securely by the secret service.

This function may block indefinitely. Use the asynchronous version in user interface threads.

setLabel

itemSetLabel

Arguments

:: (HasCallStack, MonadIO m, IsItem a, IsCancellable b)

=> a

self: an item

-> Text

label: a new label

-> Maybe b

cancellable: optional cancellation object

-> Maybe AsyncReadyCallback

callback: called when the operation completes

-> m ()

Set the label of this item.

This function returns immediately and completes asynchronously.

setLabelFinish

itemSetLabelFinish

Arguments

:: (HasCallStack, MonadIO m, IsItem a, IsAsyncResult b)

=> a

self: an item

-> b

result: asynchronous result passed to callback

-> m ()

(Can throw GError)

Complete asynchronous operation to set the label of this collection.

setLabelSync

itemSetLabelSync

Arguments

:: (HasCallStack, MonadIO m, IsItem a, IsCancellable b)

=> a

self: an item

-> Text

label: a new label

-> Maybe b

cancellable: optional cancellation object

-> m ()

(Can throw GError)

Set the label of this item.

This function may block indefinitely. Use the asynchronous version in user interface threads.

setSecret

itemSetSecret

Arguments

:: (HasCallStack, MonadIO m, IsItem a, IsCancellable b)

=> a

self: an item

-> Value

value: a new secret value

-> Maybe b

cancellable: optional cancellation object

-> Maybe AsyncReadyCallback

callback: called when the operation completes

-> m ()

Set the secret value of this item.

Each item has a single secret which might be a password or some other secret binary value.

This function returns immediately and completes asynchronously.

setSecretFinish

itemSetSecretFinish

Arguments

:: (HasCallStack, MonadIO m, IsItem a, IsAsyncResult b)

=> a

self: an item

-> b

result: asynchronous result passed to callback

-> m ()

(Can throw GError)

Complete asynchronous operation to set the secret value of this item.

setSecretSync

itemSetSecretSync

Arguments

:: (HasCallStack, MonadIO m, IsItem a, IsCancellable b)

=> a

self: an item

-> Value

value: a new secret value

-> Maybe b

cancellable: optional cancellation object

-> m ()

(Can throw GError)

Set the secret value of this item.

Each item has a single secret which might be a password or some other secret binary value.

This function may block indefinitely. Use the asynchronous version in user interface threads.

Properties

flags

A set of flags describing which parts of the secret item have been initialized.

constructItemFlags :: (IsItem o, MonadIO m) => [ItemFlags] -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “flags” property. This is rarely needed directly, but it is used by new.

getItemFlags :: (MonadIO m, IsItem o) => o -> m [ItemFlags]

Get the value of the “flags” property. When overloading is enabled, this is equivalent to

get item #flags

locked

Whether the item is locked or not.

An item may not be independently lockable separate from other items in its collection.

To lock or unlock a item use the [methodservice.lock] or [methodservice.unlock] functions.

getItemLocked :: (MonadIO m, IsItem o) => o -> m Bool

Get the value of the “locked” property. When overloading is enabled, this is equivalent to

get item #locked

service

The [classservice] object that this item is associated with and uses to interact with the actual D-Bus Secret Service.

constructItemService :: (IsItem o, MonadIO m, IsService a) => a -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “service” property. This is rarely needed directly, but it is used by new.

getItemService :: (MonadIO m, IsItem o) => o -> m Service

Get the value of the “service” property. When overloading is enabled, this is equivalent to

get item #service