notification

package
v0.0.0-...-c7fba9c Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 25, 2021 License: GPL-3.0 Imports: 5 Imported by: 0

Documentation

Overview

Package notification implements bindings to D-Bus notification specification, version 1.2, as documented at https://developer.gnome.org/notification-spec/

Index

Constants

View Source 
const ServerSelectedExpireTimeout = time.Millisecond * -1

ServerSelectedExpireTimeout requests the server to pick an expiration timeout appropriate for the message type.

Variables

This section is empty.

Functions

This section is empty.

Types

type Action 

type Action struct {
	ActionKey     string
	LocalizedText string
}

Action describes a single notification action.

ActionKey is returned in an D-Bus signal when an action is activated by the user. The text must be localized for the appropriate language.

type Category 

type Category string

Category is a string indicating the category of a notification message.

Specification: https://developer.gnome.org/notification-spec/#categories 

const (
	// DeviceCategory is a generic notification category related to hardware devices.
	DeviceCategory Category = "device"
	// DeviceAddedCategory indicates that a device was added to the system.
	DeviceAddedCategory Category = "device.added"
	// DeviceErrorCategory indicates that a device error occurred.
	DeviceErrorCategory Category = "device.error"
	// DeviceRemovedCategory indicates that a device was removed from the system.
	DeviceRemovedCategory Category = "device.removed"

	// EmailCategory is a generic notification category related to electronic mail.
	EmailCategory Category = "email"
	//EmailArrivedCategory indicates that an e-mail has arrived.
	EmailArrivedCategory Category = "email.arrived"
	// EmailBouncedCategory indicates that an e-mail message has bounced.
	EmailBouncedCategory Category = "email.bounced"

	// InstantMessageCategory is a generic notification category related to instant messages.
	InstantMessageCategory Category = "im"
	// InstantMessageErrorCategory indicates that an instant message error occurred.
	InstantMessageErrorCategory Category = "im.error"
	// InstantMessageReceivedCategory indicates that an instant mesage has been received.
	InstantMessageReceivedCategory Category = "im.received"

	// NetworkCategory is a generic notification category related to network.
	NetworkCategory Category = "network"
	// NetworkConnectedCategory indicates that a network connection has been established.
	NetworkConnectedCategory Category = "network.connected"
	// NetworkDisconnectedCategory indicates that a network connection has been lost.
	NetworkDisconnectedCategory Category = "network.disconnected"
	// NetworkErrorCategory indicates that a network error occurred.
	NetworkErrorCategory Category = "network.error"

	// PresenceCategory is a generic notification category related to on-line presence.
	PresenceCategory Category = "presence"
	// PresenceOfflineCategory indicates that a contact disconnected from the network.
	PresenceOfflineCategory Category = "presence.offline"
	// PresenceOnlineCategory indicates that a contact connected to the network.
	PresenceOnlineCategory Category = "presence.online"

	// TransferCategory is a generic notification category for file transfers or downloads.
	TransferCategory Category = "transfer"
	// TransferCompleteCategory indicates that a file transfer has completed.
	TransferCompleteCategory Category = "transfer.complete"
	// TransferErrorCategory indicates that a file transfer error occurred.
	TransferErrorCategory Category = "transfer.error"
)

type CloseReason 

type CloseReason uint32

CloseReason indicates why a notification message was closed. 

const (
	// CloseReasonExpired indicates that a notification message has expired.
	CloseReasonExpired CloseReason = 1
	// CloseReasonDismissed indicates that a notification message was dismissed by the user.
	CloseReasonDismissed CloseReason = 2
	// CloseReasonClosed indicates that a notification message was closed with an API call.
	CloseReasonClosed CloseReason = 3
	// CloseReasonUndefined indicates that no other well-known reason applies.
	CloseReasonUndefined CloseReason = 4
)

func (CloseReason) String 

func (r CloseReason) String() string

String implements the Stringer interface.

type Hint 

type Hint struct {
	Name  string
	Value interface{}
}

Hint describes supplementeary information that may be used by the server.

Various helpers create hint objects of specifc purpose.

Specification: https://developer.gnome.org/notification-spec/#hints

func WithActionIcons 

func WithActionIcons() Hint

WithActionIcons returns a hint asking the server to use action key as icon names.

A server that has the "action-icons" capability will attempt to interpret any action key as a named icon. The localized display name will be used to annotate the icon for accessibility purposes. The icon name should be compliant with the Freedesktop.org Icon Naming Specification.

Requires server version >= 1.2

func WithCategory 

func WithCategory(c Category) Hint

WithCategory returns a hint asking the server to set message category.

func WithDesktopEntry 

func WithDesktopEntry(desktopEntryName string) Hint

WithDesktopEntry returns a hint asking the server to associate a desktop file with a message.

The desktopEntryName is the name of the desktop file without the ".desktop" extension. The server may use this information to derive correct icon, for logging, etc.

func WithImageFile 

func WithImageFile(path string) Hint

WithImageFile returns a hint asking the server display an image loaded from file.

When multiple hits related to images are used, the following priority list applies: 1) "image-data" (not implemented in Go). 2) "image-path", as provided by WithImageFile. 3) Message.Icon field.

func WithPointToX 

func WithPointToX(x int) Hint

WithPointToX returns a hint asking the server to point the notification at a specific X coordinate.

The coordinate is in desktop pixel units. Both X and Y hints must be included in the message.

func WithPointToY 

func WithPointToY(y int) Hint

WithPointToY returns a hint asking the server to point the notification at a specific Y coordinate.

The coordinate is in desktop pixel units. Both X and Y hints must be included in the message.

func WithResident 

func WithResident() Hint

WithResident returns a hint asking the server to keep the message after an action is invoked.

When set the server will not automatically remove the notification when an action has been invoked. The notification will remain resident in the server until it is explicitly removed by the user or by the sender. This hint is likely only useful when the server has the "persistence" capability.

Requires server version >= 1.2

func WithSoundFile 

func WithSoundFile(path string) Hint

WithSoundFile returns a hint asking the server to play a sound loaded from file.

func WithSoundName 

func WithSoundName(name string) Hint

WithSoundName returns a hint asking the server to play a sound from the sound theme.

func WithSuppressSound 

func WithSuppressSound() Hint

WithSuppressSound returns a hint asking the server not to play any notification sounds.

func WithTransient 

func WithTransient() Hint

WithTransient returns a hint asking the server to bypass message persistence.

When set the server will treat the notification as transient and by-pass the server's persistence capability, if it should exist.

Requires server version >= 1.2

func WithUrgency 

func WithUrgency(u Urgency) Hint

WithUrgency returns a hint asking the server to set message urgency.

Notification servers may show messages with higher urgency before messages with lower urgency. In addition some urgency levels may not be shown when the user has enabled a do-not-distrub mode.

type ID 

type ID uint32

ID is the opaque identifier of a notification assigned by the server.

Notifications with known identifiers can be closed or updated. The identifier is valid within one desktop session and should not be used unless the calling process initially sent the message.

type Message 

type Message struct {
	AppName       string
	Icon          string
	Summary       string
	Body          string
	ExpireTimeout time.Duration // Effective resolution in milliseconds with 31-bit range.
	ReplacesID    ID
	Actions       []Action
	Hints         []Hint
}

Message describes a single notification message.

The notification should be related to a specific application, as indicated by AppName. In practice this should be the name of the desktop file and could be also accompanied by an appropriate hint indicating which icon to use.

Message must include a summary and should include a body. The body may use HTML-like markup language to include bold, italic or underline text, as well as to include images and hyperlinks.

A notification can automatically expire after the given number of milliseconds. This is separate from the notification being visible or invisible on-screen. Expired notifications are removed from persistent message roster, if one is supported. Two special values are recognized. When the expiration timeout is zero a message never expires. When the expiration timeout is -1 a message expires after a server-defined duration which may vary for the type of the notification message sent.

A notification may replace an existing notification by setting the ReplacesID to a non-zero value. This only works if the notification server was not re-started and should be used for as long as the sender process is alive, as sending the identifier across session startup boundary has no chance of working correctly.

A notification may optionally carry a number of hints that further customize it in a specific way. Refer to various hint constructors for details.

A notification may optionally also carry one of several actions. If supported, actions can be invoked by the user, broadcasting a notification response back to the session. This mechanism only works if there is someone listening for the action being triggered.

In all cases, the specific notification must take into account the capabilities of the server. For instance, if a server does not support body markup, then such markup is not automatically stripped by either the client or the server.

type Observer 

type Observer interface {
	// NotificationClosed is called when a notification is either closed or removed
	// from the persistent roster.
	NotificationClosed(id ID, reason CloseReason) error
	// ActionInvoked is caliled when one of the notification message actions is
	// clicked by the user.
	ActionInvoked(id ID, actionKey string) error
}

Observer is an interface for observing interactions with notification messages.

An observer can be used to either observe a notification being closed or dismissed or to react to actions being invoked by the user. Practical implementations must remember the ID of the message they have sent to filter out other notifications.

type Server 

type Server struct {
	// contains filtered or unexported fields
}

Server holds a connection to a notification server interactions.

func New 

func New(conn *dbus.Conn) *Server

New returns new connection to a freedesktop.org message notification server.

Each server offers specific capabilities. It is advised to provide graceful degradation of functionality, depending on the supported capabilities, so that the notification messages are useful on a wide range of desktop environments.

func (*Server) CloseNotification 

func (srv *Server) CloseNotification(id ID) error

CloseNotification closes a notification message with the given ID.

func (*Server) ObserveNotifications 

func (srv *Server) ObserveNotifications(ctx context.Context, observer Observer) (err error)

ObserveNotifications blocks and processes message notification signals.

The bus connection is configured to deliver signals from the notification server. All received signals are dispatched to the provided observer. This process continues until stopped by the context, or if an error occurs.

func (*Server) SendNotification 

func (srv *Server) SendNotification(msg *Message) (ID, error)

SendNotification sends a new notification or updates an existing notification. In both cases the ID of the notification, as assigned by the server, is returned. The ID can be used to cancel a notification, update it or react to invoked user actions.

func (*Server) ServerCapabilities 

func (srv *Server) ServerCapabilities() ([]ServerCapability, error)

ServerCapabilities returns the list of notification capabilities provided by the session.

func (*Server) ServerInformation 

func (srv *Server) ServerInformation() (name, vendor, version, specVersion string, err error)

ServerInformation returns the information about the notification server.

type ServerCapability 

type ServerCapability string

ServerCapability describes a single capability of the notification server. 

const (
	// ActionIconsCapability indicates that the server supports using icons
	// instead of text for displaying actions. Using icons for actions must be
	// enabled on a per-notification basis using the "action-icons" hint.
	ActionIconsCapability ServerCapability = "action-icons"
	// ActionsCapability indicates that the server will provide the specified
	// actions to the user. Even if this cap is missing, actions may still be
	// specified by the client, however the server is free to ignore them.
	ActionsCapability ServerCapability = "actions"
	// BodyCapability indicates that the server supports body text. Some
	// implementations may only show the summary (for instance, onscreen
	// displays, marquee/scrollers).
	BodyCapability ServerCapability = "body"
	// BodyHyperlinksCapability indicates that the server supports hyperlinks in
	// the notifications.
	BodyHyperlinksCapability ServerCapability = "body-hyperlinks"
	// BodyImagesCapability indicates that the server supports images in the
	// notifications.
	BodyImagesCapability ServerCapability = "body-images"
	// BodyMarkupCapability indicates that the server supports markup in the
	// body text. If marked up text is sent to a server that does not give this
	// cap, the markup will show through as regular text so must be stripped
	// clientside.
	BodyMarkupCapability ServerCapability = "body-markup"
	// IconMultiCapability indicates that the server will render an animation of
	// all the frames in a given image array. The client may still specify
	// multiple frames even if this cap and/or "icon-static" is missing, however
	// the server is free to ignore them and use only the primary frame.
	IconMultiCapability ServerCapability = "icon-multi"
	// IconStaticCapability indicates that the server supports display of
	// exactly one frame of any given image array. This value is mutually
	// exclusive with "icon-multi", it is a protocol error for the server to
	// specify both.
	IconStaticCapability ServerCapability = "icon-static"
	// PersistenceCapability indicates that the server supports persistence of
	// notifications. Notifications will be retained until they are acknowledged
	// or removed by the user or recalled by the sender. The presence of this
	// capability allows clients to depend on the server to ensure a
	// notification is seen and eliminate the need for the client to display a
	// reminding function (such as a status icon) of its own.
	PersistenceCapability ServerCapability = "persistence"
	// SoundCapability indicates that the server supports sounds on
	// notifications. If returned, the server must support the "sound-file" and
	// "suppress-sound" hints.
	SoundCapability ServerCapability = "sound"
)

type Urgency 

type Urgency byte

Urgency describes the importance of a notification message.

Specification: https://developer.gnome.org/notification-spec/#urgency-levels 

const (
	// LowUrgency indicates that a notification message is below normal priority.
	LowUrgency Urgency = 0
	// NormalUrgency indicates that a notification message has the regular priority.
	NormalUrgency Urgency = 1
	// CriticalUrgency indicates that a notification message is above normal priority.
	CriticalUrgency Urgency = 2
)

func (Urgency) String 

func (u Urgency) String() string

String implements the Stringer interface.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.