notify

README

Schnouki/notify

Package notify provides DBus notifications as specified in the Freedesktop Notifications Specification.

Documentation

Overview

Package notify provides tray notifications via D-Bus freedesktop.org notifications.

WARNING: You are free to use this package, however please note that the API is likely to be unstable till all the functionality is implemented, and there is a lot missing!

There is not much you need to do use this package, just start sending notifications:

func main() {
	id, err := notify.SendMsg("My summary", "My body, which some notification services don't show")
	if err != nil {
		fmt.Println(err)
	}
	// You can also ignore the error message, in which case failed notifications are ignored,
	// because let's be honest, who cares if the notifications get delivered or not? ;-)
	notify.ReplaceUrgentMsg("Forget that <i>last message</i>", "", notify.LowUrgency)
}

The defaults are a timeout of 3 seconds for notifications and a normal urgency, with everything being empty. You are free to change these via Init, SetName, SetTimeout, SetIconPath, and SetUrgency.

Alternatively, you can create your own Notification template, via New.

The notify package has been developed according to https://developer.gnome.org/notification-spec, although there is a lot of functionality missing.

There is some markup that you can use in the summary and body parts of a notification:

<b>bold</b>
<i>italic</i>
<u>underline</u>
<a href="...">hyperlink</a>
<img src="..." alt="..." />

I have tried to implement this in the Go philosophy, please let me know if I can improve it somehow.

Example

This is a simple example for how to use the notify package.

notify.SetName("Simple")

notify.SendMsg("Starting up the Simple Server", "")
time.Sleep(3 * time.Second)
id, _ = notify.SendUrgentMsg("Oops, made a big mistake!", "", notify.CriticalUrgency)
time.Sleep(1 * time.Second)
notify.ReplaceMsg(id, "Ha! Fixed that, thank goodness!", "")

Index

• func IconPath() string
• func Init(name, icon string, timeout time.Duration, urgency NotificationUrgency)
• func Name() string
• func ReplaceMsg(id uint32, summary, body string) (newID uint32, err error)
• func ReplaceUrgentMsg(id uint32, summary, body string, urgency NotificationUrgency) (newID uint32, err error)
• func SendMsg(summary, body string) (id uint32, err error)
• func SendUrgentMsg(summary, body string, urgency NotificationUrgency) (id uint32, err error)
• func ServiceAvailable() bool
• func SetIconPath(path string)
• func SetName(name string)
• func SetTimeout(dur time.Duration)
• func SetUrgency(urgency NotificationUrgency)
• func Timeout() time.Duration
• type Notification
  • func New(name, summary, body, icon string, timeout time.Duration, ...) *Notification
  • func (n Notification) ReplaceMsg(summary, body string) (err error)
  • func (n Notification) ReplaceUrgentMsg(summary, body string, urgency NotificationUrgency) (err error)
  • func (n Notification) Send() (err error)
• type NotificationUrgency
  • func Urgency() NotificationUrgency

Examples

• Package

Functions

func IconPath

func IconPath() string

IconPath returns the icon path for the implicit notification.

func Init

func Init(name, icon string, timeout time.Duration, urgency NotificationUrgency)

Init sets the defaults for the implicit notification.

func Name

func Name() string

Name returns the name for the implicit notification.

func ReplaceMsg

func ReplaceMsg(id uint32, summary, body string) (newID uint32, err error)

ReplaceMsg replaces the already existing notification with the ID id with summary and body, returning the new ID and an error if it fails. It takes all other values from the implicit notification object.

In particular, if the notification it is replacing had other properties, such as another urgency, these are also replaced by the defaults in the implicit notification!

func ReplaceUrgentMsg

func ReplaceUrgentMsg(id uint32, summary, body string, urgency NotificationUrgency) (newID uint32, err error)

ReplaceUrgentMsg replaces the already existing notification with the ID id with summary and body and urgency, returning the new ID and an error if it fails. It takes all other values from the implicit notification object.

func SendMsg

func SendMsg(summary, body string) (id uint32, err error)

SendMsg sends the summary and the body as a notification, returning a unique notification ID and an error, possibly nil. It takes all other values from the implicit notification object.

func SendUrgentMsg

func SendUrgentMsg(summary, body string, urgency NotificationUrgency) (id uint32, err error)

SendUrgentMsg sends the summary and the body as a notification with the urgency of urgency, and returns a unique notification ID and an error, possibly nil. Otherwise it is like SendMsg.

func ServiceAvailable

func ServiceAvailable() bool

ServiceAvailable returns true if notifications via DBus are available.

First, it initiates a connection via DBus to find out whether DBus is available, then it contacts the notification service to find out if it is available. If one or the other is not available, it returns false.

Before using notify, it is a good idea (though not necessary) to test if this service is available. If it's not available, this does not tell you why though. Maybe another day.

func SetIconPath

func SetIconPath(path string)

SetIconPath sets the icon path for the implicit notification.

func SetName

func SetName(name string)

SetName sets the name for the implicit notification.

func SetTimeout

func SetTimeout(dur time.Duration)

SetTimeout sets the timeout for the implicit notification.

func SetUrgency

func SetUrgency(urgency NotificationUrgency)

SetUrgency sets the urgency level for the implicit notification. It can be either LowUrgency, NormalUrgency, or CriticalUrgency.

func Timeout

func Timeout() time.Duration

Timeout returns the timeout for the implicit notification.

Types

type Notification

type Notification struct {
	// Name represents the application name sending the notification.  This is
	// optional and can be the empty string "".
	Name string
	// Summary represents the subject of the notification.
	Summary string
	// Body represents the main body with extra details. Some notification
	// daemons ignore the body; it is optional and can be the empty string "".
	Body string

	// IconPath is a path to an icon that should be used for the notification.
	// Some notification daemons ignore the icon path; it is optional and can
	// be the empty string "".
	IconPath string
	// Timeout is the requested timeout for the notification. Some notification
	// daemons override the requested timeout. A value of 0 is a request that
	// it not timeout at all.
	Timeout time.Duration
	// Urgency determines the urgency of the notification, which can be one of
	// LowUrgency, NormalUrgency, and CriticalUrgency.
	Urgency NotificationUrgency

	// Id is the ID of the notification. It is 0 initially, and will be
	// updated when calling Send or one of the Replace methods.
	Id uint32
}

Notification is there to provide you with full power of your notifications. It is possible for you to use a Notification as you use the notify library without them. This allows for multiple defaults.

For example:

func main() {
	critical := notify.New("prog", "", "", "critical-icon.png", time.Duration(0), notify.CriticalUrgency)
	boring := notify.New("prog", "", "", "low-icon.png", 1 * time.Second, notify.LowUrgency)
	boring.ReplaceMsg("Nothing is happening... boring!", "")
	critical.ReplaceMsg("Your computer is on fire!", "Here is what you should do:\n ...")
}

func New

func New(name, summary, body, icon string, timeout time.Duration, urgency NotificationUrgency) *Notification

New returns a pointer to a new Notification.

func (Notification) ReplaceMsg

func (n Notification) ReplaceMsg(summary, body string) (err error)

ReplaceMsg is identical to notify.ReplaceMsg, except that the rest of the values come from n.

func (Notification) ReplaceUrgentMsg

func (n Notification) ReplaceUrgentMsg(summary, body string, urgency NotificationUrgency) (err error)

ReplaceUrgentMsg is identical to notify.ReplaceUrgentMsg, except that the rest of the values come from n.

func (Notification) Send

func (n Notification) Send() (err error)

Send sends the notification n as it is, and returns an err, possibly nil.

type NotificationUrgency

type NotificationUrgency byte

NotificationUrgency can be either LowUrgency, NormalUrgency, and CriticalUrgency. It is conceivable that some notification daemons make no distinction between the different urgencies, but enough do that it makes sense to use them.

const (
	LowUrgency      NotificationUrgency = iota // LowUrgency probably shouldn't even be shown ;-)
	NormalUrgency                              // NormalUrgency is for information that is interesting.
	CriticalUrgency                            // CriticalUrgency is for errors or severe events.
)

func Urgency

func Urgency() NotificationUrgency

Urgency returns the urgency level for the implicit notification. It can be either LowUrgency, NormalUrgency, or CriticalUrgency.