notify

README

goulash/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.

package main

import (
	"time"

	"github.com/goulash/notify"
)

func main() {
	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) Replace(id uint32) (newID uint32, err error)
  • func (n Notification) ReplaceMsg(id uint32, summary, body string) (newID uint32, err error)
  • func (n Notification) ReplaceUrgentMsg(id uint32, summary, body string, urgency NotificationUrgency) (newID uint32, err error)
  • func (n Notification) Send() (id uint32, err error)
  • func (n Notification) SendMsg(summary, body string) (id uint32, err error)
  • func (n Notification) SendUrgentMsg(summary, body string, urgency NotificationUrgency) (id uint32, 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
}

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.SendMsg("Nothing is happening... boring!", "")
	critical.SendMsg("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) Replace

func (n Notification) Replace(id uint32) (newID uint32, err error)

Replace replaces the notification with the ID id as it is, and returns the new ID and an error if one occured.

func (Notification) ReplaceMsg

func (n Notification) ReplaceMsg(id uint32, summary, body string) (newID uint32, 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(id uint32, summary, body string, urgency NotificationUrgency) (newID uint32, 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() (id uint32, err error)

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

func (Notification) SendMsg

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

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

func (Notification) SendUrgentMsg

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

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

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.