notify

README

notify

Notify is a go library for interacting with the dbus notification service defined here: https://developer.gnome.org/notification-spec/

It can deliver notifications to desktop using dbus communication, ala how libnotify does it. It has so far only been testing with gnome and gnome-shell 3.16/3.18 in Arch Linux.

Please note notify is still in a very early change and no APIs are locked until a 1.0 is released.

More testers are very welcome =)

Depends on:

• godbus.

Quick intro

See example: main.go.

Clone repo and go to examples folder:

go run main.go

TODO

• Add callback support aka dbus signals.
• Tests. I am very interested in any ideas for writing some (useful) tests for this.

See also

The Gnome notification spec https://developer.gnome.org/notification-spec/.

Contributors

Thanks to user emersion for great ideas on receiving signals.

License

GPLv3

Documentation

Overview

Package notify is a wrapper around godbus for dbus notification interface See: https://developer.gnome.org/notification-spec/ and https://github.com/godbus/dbus

The package provides exported methods for simple usage, e.g. just show a notification. It also provides the interface Notifier that includes event delivery for notifications. Note that if you use New() to create a notifier, it is the caller responsibility to also drain the channels for ActionInvoked() and NotificationClosed().

Each notification created is allocated a unique ID by the server (see Notification). This ID is unique within the dbus session, and is an increasing number. While the notification server is running, the ID will not be recycled unless the capacity of a uint32 is exceeded.

The ID can be used to hide the notification before the expiration timeout is reached (see CloseNotification).

The ID can also be used to atomically replace the notification with another (Notification.ReplaceID). This allows you to (for instance) modify the contents of a notification while it's on-screen.

Index

• func GetCapabilities(conn *dbus.Conn) ([]string, error)
• func SendNotification(conn *dbus.Conn, note Notification) (uint32, error)
• type ActionInvokedSignal
• type Notification
• type NotificationClosedSignal
• type Notifier
  • func New(conn *dbus.Conn) (Notifier, error)
• type Reason
  • func (r Reason) String() string
• type ServerInformation
  • func GetServerInformation(conn *dbus.Conn) (ServerInformation, error)

Functions

func GetCapabilities

func GetCapabilities(conn *dbus.Conn) ([]string, error)

GetCapabilities gets the capabilities of the notification server. This call takes no parameters. It returns an array of strings. Each string describes an optional capability implemented by the server.

See also: https://developer.gnome.org/notification-spec/ GetCapabilities provide an exported method for this operation

func SendNotification

func SendNotification(conn *dbus.Conn, note Notification) (uint32, error)

SendNotification is provided for convenience. Use if you only want to deliver a notification and dont care about events.

Types

type ActionInvokedSignal

type ActionInvokedSignal struct {
	ID        uint32
	ActionKey string
}

type Notification

type Notification struct {
	AppName       string
	ReplacesID    uint32 // (atomically) replaces notification with this ID. Optional.
	AppIcon       string // See icons here: http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html Optional.
	Summary       string
	Body          string
	Actions       []string // tuples of (action_key, label), e.g.: []string{"cancel", "Cancel", "open", "Open"}
	Hints         map[string]dbus.Variant
	ExpireTimeout int32 // milliseconds to show notification
}

Notification holds all information needed for creating a notification

type NotificationClosedSignal

type NotificationClosedSignal struct {
	ID     uint32
	Reason Reason
}

type Notifier

type Notifier interface {
	SendNotification(n Notification) (uint32, error)
	GetCapabilities() ([]string, error)
	GetServerInformation() (ServerInformation, error)
	CloseNotification(id int) (bool, error)
	NotificationClosed() <-chan *NotificationClosedSignal
	ActionInvoked() <-chan *ActionInvokedSignal
	Close() error
}

Notifier is an interface for implementing the operations supported by the freedesktop DBus Notifications object.

New() sets up a Notifier that listens on dbus' signals regarding Notifications: NotificationClosed and ActionInvoked.

Note this also means the caller MUST consume output from these channels, given in methods NotificationClosed() and ActionInvoked(). Users that only want to send a simple notification, but don't care about interactions, see exported method: SendNotification(conn, Notification)

Caller is also responsible to call Close() before exiting, to shut down event loop and cleanup.

func New

func New(conn *dbus.Conn) (Notifier, error)

New creates a new Notifier using conn. See also: Notifier

type Reason

type Reason uint32

Reason for the closed notification

const (
	// ReasonExpired when a notification expired
	ReasonExpired Reason = 1

	// ReasonDismissedByUser when a notification has been dismissed by a user
	ReasonDismissedByUser Reason = 2

	// ReasonClosedByCall when a notification has been closed by a call to CloseNotification
	ReasonClosedByCall Reason = 3

	// ReasonUnknown when as notification has been closed for an unknown reason
	ReasonUnknown Reason = 4
)

func (Reason) String

func (r Reason) String() string

type ServerInformation

type ServerInformation struct {
	Name        string
	Vendor      string
	Version     string
	SpecVersion string
}

ServerInformation is a holder for information returned by GetServerInformation call.

func GetServerInformation

func GetServerInformation(conn *dbus.Conn) (ServerInformation, error)

GetServerInformation returns the information on the server.

org.freedesktop.Notifications.GetServerInformation

 GetServerInformation Return Values

		Name		 Type	  Description
		name		 STRING	  The product name of the server.
		vendor		 STRING	  The vendor name. For example, "KDE," "GNOME," "freedesktop.org," or "Microsoft."
		version		 STRING	  The server's version number.
		spec_version STRING	  The specification version the server is compliant with.