Documentation
¶
Overview ¶
Package notify sends desktop notifications over org.freedesktop.Notifications and reports the actions the user takes on them.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Action ¶
type Action struct {
Key, Label string
}
Action is one notification action: Key is what the server reports back in ActionInvoked, Label is what the user sees. The key "default" is the action taken when the notification itself is clicked.
type Event ¶
Event is an action the user took on a notification this Notifier sent. ActivationToken is the token the server issued for that notification just before the action, or empty when it issued none. System is true for a system notification, whose NoticeID is empty like a summary's.
type Message ¶
type Message struct {
NoticeID, Summary, Body string
Urgency byte
Actions []Action
// Covers lists the notice IDs a summary message stands for, so the caller
// can mark each of them notified once it is sent. It is empty for a
// single-notice message and never sent on the wire: Send ignores it.
Covers []string
// System marks a notification about the host's health rather than a
// notice. Its NoticeID is empty, like a summary's; the Events of a click
// on it carry System so the two can be told apart.
System bool
// Key names the condition a system notification reports (a monitor and
// its target, say "disk:/var/tmp/portage"); it is empty for notices.
// ReplacesID is the ID of the earlier notification to replace. Send
// passes it on only when this Notifier recorded that ID under the current
// server with the same non-empty Key; otherwise the message goes out as
// a new notification.
Key string
ReplacesID uint32
}
Message is one notification. A summary message has an empty NoticeID. Summary and Body are notice-supplied plain text: Send passes the summary as is and escapes the body only for a server that advertises body-markup. Urgency is the spec's urgency hint: 0 low, 1 normal, 2 critical.
type Notifier ¶
type Notifier struct {
// contains filtered or unexported fields
}
Notifier sends notifications on one connection and reports the actions taken on them. It is safe for concurrent use; concurrent Sends do not wait for one another.
The ID a signal names is recorded by Send only after the Notify reply reaches it, and godbus hands that reply to Send and a signal right behind it to the reader concurrently. So while a Send is in flight, a signal from the server for an unknown ID is parked rather than dropped; the Send that records the ID replays the parked signals that name it, and once no Send is in flight the rest are known to be foreign and are discarded. No lock is ever held across a bus call.
func New ¶
New subscribes to the notification server's signals on conn and starts the reader that turns them into Events. No server needs to be on the bus: one that appears later is heard. conn must stay open for as long as the Notifier is used (some servers withdraw an application's notifications when its connection goes away); New never closes it. A nil log discards.
func (*Notifier) Close ¶ added in v0.37.0
Close withdraws the notification Send returned as id for the condition key, with CloseNotification. It calls the server only when id passes the same check as Send's ReplacesID (see ownedLocked): a stale, foreign or unknown id, or an empty key, sends nothing and returns nil, so neither another application's notification nor another of this Notifier's is ever closed. The call goes to the owner id was checked against, by unique name, so a server that took the name since never receives it: the call fails instead.
The spec lets a server answer with an error for a notification that no longer exists, and some do: the error, wrapped with the id, is for the caller to log at DEBUG, never to retry. ctx bounds the call as it does for Send.
func (*Notifier) Events ¶
Events reports the actions taken on this Notifier's notifications. The channel is never closed; it simply goes quiet when the connection ends.
func (*Notifier) Send ¶
Send shows m and returns the ID the server assigned to it. The summary is sent as plain text; the body is escaped only when the server advertises body-markup, and sent as is otherwise. m.Actions are sent in order as key/label pairs. Errors name the notice, or the condition key of a system notification.
m.ReplacesID goes out as replaces_id only when this Notifier recorded it under the current server owner for the same non-empty m.Key; otherwise it is 0 and the server shows a new notification. A restarted server numbers its notifications from 1 again, so an ID kept from before the restart may name another application's notification or another of this Notifier's, which must not be overwritten. For the same reason a replacement is sent to the owner its ID was checked against, by unique name; when that owner has left the bus by the time of the call, the message is sent once more by the well-known name, as a new notification.
ctx should carry a deadline: a server that accepts the call and never answers is otherwise waited for up to 25 s. A slow or hung server delays only this Send, never another Send or the delivery of Events.
Source Files