mirror of
https://github.com/octoleo/syncthing.git
synced 2024-12-23 11:28:59 +00:00
657 lines
15 KiB
Groff
657 lines
15 KiB
Groff
.\" Man page generated from reStructuredText.
|
|
.
|
|
.TH "SYNCTHING-EVENT-API" "7" "July 19, 2015" "v0.11" "Syncthing"
|
|
.SH NAME
|
|
syncthing-event-api \- Event API
|
|
.
|
|
.nr rst2man-indent-level 0
|
|
.
|
|
.de1 rstReportMargin
|
|
\\$1 \\n[an-margin]
|
|
level \\n[rst2man-indent-level]
|
|
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
-
|
|
\\n[rst2man-indent0]
|
|
\\n[rst2man-indent1]
|
|
\\n[rst2man-indent2]
|
|
..
|
|
.de1 INDENT
|
|
.\" .rstReportMargin pre:
|
|
. RS \\$1
|
|
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
|
|
. nr rst2man-indent-level +1
|
|
.\" .rstReportMargin post:
|
|
..
|
|
.de UNINDENT
|
|
. RE
|
|
.\" indent \\n[an-margin]
|
|
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.nr rst2man-indent-level -1
|
|
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
|
..
|
|
.SH DESCRIPTION
|
|
.sp
|
|
Syncthing provides a simple long polling interface for exposing events from the
|
|
core utility towards a GUI.
|
|
.sp
|
|
To receive events, perform a HTTP GET of \fB/rest/events?since=<lastSeenID>\fP,
|
|
where \fB<lastSeenID>\fP is the ID of the last event you\(aqve already seen or zero.
|
|
Syncthing returns a JSON encoded array of event objects, starting at the event
|
|
just after the one with the last seen ID. There is a limit to the number of
|
|
events buffered, so if the rate of events is high or the time between polling
|
|
calls is long some events might be missed. This can be detected by noting a
|
|
discontinuity in the event IDs.
|
|
.sp
|
|
If no new events are produced since \fB<lastSeenID>\fP, the HTTP call blocks and
|
|
waits for new events to happen before returning, or if no new events are
|
|
produced within 60 seconds, times out.
|
|
.sp
|
|
To receive only a limited number of events, add the \fBlimit=n\fP parameter with a
|
|
suitable value for \fBn\fP and only the \fIlast\fP \fBn\fP events will be returned. This
|
|
can be used to catch up with the latest event ID after a disconnection for
|
|
example: \fB/rest/events?since=0&limit=1\fP\&.
|
|
.SH EVENT STRUCTURE
|
|
.sp
|
|
Each event is represented by an object similar to the following:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
"id": 2,
|
|
"type": "DeviceConnected",
|
|
"time": "2014\-07\-13T21:04:33.687836696+02:00",
|
|
"data": {
|
|
"addr": "172.16.32.25:22000",
|
|
"id": "NFGKEKE\-7Z6RTH7\-I3PRZXS\-DEJF3UJ\-FRWJBFO\-VBBTDND\-4SGNGVZ\-QUQHJAG"
|
|
}
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
The top level keys \fBid\fP, \fBtime\fP, \fBtype\fP and \fBdata\fP are always present,
|
|
though \fBdata\fP may be \fBnull\fP\&.
|
|
.INDENT 0.0
|
|
.TP
|
|
.B id
|
|
A monotonically increasing integer. The first event generated has id \fB1\fP,
|
|
the next has id \fB2\fP etc.
|
|
.TP
|
|
.B time
|
|
The time the event was generated.
|
|
.TP
|
|
.B type
|
|
Indicates the type of (i.e. reason for) the event and is one of the event
|
|
types below.
|
|
.TP
|
|
.B data
|
|
An object containing optional extra information; the exact structure is
|
|
determined by the event type.
|
|
.UNINDENT
|
|
.SH EVENTS
|
|
.SS ConfigSaved
|
|
.sp
|
|
Emitted after the config has been saved by the user or by Syncthing
|
|
itself.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
"id": 50,
|
|
"type": "ConfigSaved",
|
|
"time": "2014\-12\-13T00:09:13.5166486Z",
|
|
"data":{
|
|
"Version": 7,
|
|
"Options": { ... },
|
|
"GUI": { ... },
|
|
"Devices": [ ... ],
|
|
"Folders": [ ... ]
|
|
}
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS DeviceConnected
|
|
.sp
|
|
Generated each time a connection to a device has been established.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
"id": 2,
|
|
"type": "DeviceConnected",
|
|
"time": "2014\-07\-13T21:04:33.687836696+02:00",
|
|
"data": {
|
|
"addr": "172.16.32.25:22000",
|
|
"id": "NFGKEKE\-7Z6RTH7\-I3PRZXS\-DEJF3UJ\-FRWJBFO\-VBBTDND\-4SGNGVZ\-QUQHJAG"
|
|
}
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS DeviceDisconnected
|
|
.sp
|
|
Generated each time a connection to a device has been terminated.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
"id": 48,
|
|
"type": "DeviceDisconnected",
|
|
"time": "2014\-07\-13T21:18:52.859929215+02:00",
|
|
"data": {
|
|
"error": "unexpected EOF",
|
|
"id": "NFGKEKE\-7Z6RTH7\-I3PRZXS\-DEJF3UJ\-FRWJBFO\-VBBTDND\-4SGNGVZ\-QUQHJAG"
|
|
}
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
\fBNOTE:\fP
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
The error key contains the cause for disconnection, which might not
|
|
necessarily be an error as such. Specifically, "EOF" and "unexpected
|
|
EOF" both signify TCP connection termination, either due to the other
|
|
device restarting or going offline or due to a network change.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS DeviceDiscovered
|
|
.sp
|
|
Emitted when a new device is discovered using local discovery.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
"id": 13,
|
|
"type": "DeviceDiscovered",
|
|
"time": "2014\-07\-17T13:28:05.043465207+02:00",
|
|
"data": {
|
|
"addrs": [
|
|
"172.16.32.25:22000"
|
|
],
|
|
"device": "NFGKEKE\-7Z6RTH7\-I3PRZXS\-DEJF3UJ\-FRWJBFO\-VBBTDND\-4SGNGVZ\-QUQHJAG"
|
|
}
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS DeviceRejected
|
|
.sp
|
|
Emitted when there is a connection from a device we are not configured
|
|
to talk to.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
"id": 24,
|
|
"type": "DeviceRejected",
|
|
"time": "2014\-08\-19T10:43:00.562821045+02:00",
|
|
"data": {
|
|
"address": "127.0.0.1:51807",
|
|
"device": "EJHMPAQ\-OGCVORE\-ISB4IS3\-SYYVJXF\-TKJGLTU\-66DIQPF\-GJ5D2GX\-GQ3OWQK"
|
|
}
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS DownloadProgress
|
|
.sp
|
|
Emitted during file downloads for each folder for each file. By default
|
|
only a single file in a folder is handled at the same time, but custom
|
|
configuration can cause multiple files to be shown.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
"id": 221,
|
|
"type": "DownloadProgress",
|
|
"time": "2014\-12\-13T00:26:12.9876937Z",
|
|
"data": {
|
|
"folder1": {
|
|
"file1": {
|
|
"Total": 800,
|
|
"Pulling": 2,
|
|
"CopiedFromOrigin": 0,
|
|
"Reused": 633,
|
|
"CopiedFromElsewhere": 0,
|
|
"Pulled": 38,
|
|
"BytesTotal": 104792064,
|
|
"BytesDone": 87883776
|
|
},
|
|
"dir\e\efile2": {
|
|
"Total": 80,
|
|
"Pulling": 2,
|
|
"CopiedFromOrigin": 0,
|
|
"Reused": 0,
|
|
"CopiedFromElsewhere": 0,
|
|
"Pulled": 32,
|
|
"BytesTotal": 10420224,
|
|
"BytesDone": 4128768
|
|
}
|
|
},
|
|
"folder2": {
|
|
"file3": {
|
|
"Total": 800,
|
|
"Pulling": 2,
|
|
"CopiedFromOrigin": 0,
|
|
"Reused": 633,
|
|
"CopiedFromElsewhere": 0,
|
|
"Pulled": 38,
|
|
"BytesTotal": 104792064,
|
|
"BytesDone": 87883776
|
|
},
|
|
"dir\e\efile4": {
|
|
"Total": 80,
|
|
"Pulling": 2,
|
|
"CopiedFromOrigin": 0,
|
|
"Reused": 0,
|
|
"CopiedFromElsewhere": 0,
|
|
"Pulled": 32,
|
|
"BytesTotal": 10420224,
|
|
"BytesDone": 4128768
|
|
}
|
|
}
|
|
}
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.IP \(bu 2
|
|
\fBTotal\fP \- total number of blocks in the file
|
|
.IP \(bu 2
|
|
\fBPulling\fP \- number of blocks currently being downloaded
|
|
.IP \(bu 2
|
|
\fBCopiedFromOrigin\fP \- number of blocks copied from the file we are
|
|
about to replace
|
|
.IP \(bu 2
|
|
\fBReused\fP \- number of blocks reused from a previous temporary file
|
|
.IP \(bu 2
|
|
\fBCopiedFromElsewhere\fP \- number of blocks copied from other files or
|
|
potentially other folders
|
|
.IP \(bu 2
|
|
\fBPulled\fP \- number of blocks actually downloaded so far
|
|
.IP \(bu 2
|
|
\fBBytesTotal\fP \- approximate total file size
|
|
.IP \(bu 2
|
|
\fBBytesDone\fP \- approximate number of bytes already handled (already
|
|
reused, copied or pulled)
|
|
.UNINDENT
|
|
.sp
|
|
Where block size is 128KB.
|
|
.sp
|
|
Files/folders appearing in the event data imply that the download has
|
|
been started for that file/folder, where disappearing implies that the
|
|
downloads has been finished or failed for that file/folder. There is
|
|
always a last event emitted with no data, which implies all downloads
|
|
being finished/failed.
|
|
.SS FolderCompletion
|
|
.sp
|
|
The \fBFolderCompletion\fP event is emitted when the local or remote
|
|
contents for a folder changes. It contains the completion percentage for
|
|
a given remote device and is emitted once per currently connected remote
|
|
device.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
"id": 84,
|
|
"type": "FolderCompletion",
|
|
"time": "2015\-04\-17T14:14:27.043576583+09:00",
|
|
"data": {
|
|
"completion": 100,
|
|
"device": "I6KAH76\-66SLLLB\-5PFXSOA\-UFJCDZC\-YAOMLEK\-CP2GB32\-BV5RQST\-3PSROAU",
|
|
"folder": "default"
|
|
}
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS FolderErrors
|
|
.sp
|
|
The \fBFolderErrors\fP event is emitted when a folder cannot be successfully
|
|
synchronized. The event contains the ID of the affected folder and a list of
|
|
errors for files or directories therein. This list of errors is obsolete once
|
|
the folder changes state to \fBsyncing\fP \- if errors remain after the next
|
|
synchronization attempt, a new \fBFolderErrors\fP event is emitted.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
"id": 132,
|
|
"type": "FolderErrors",
|
|
"time": "2015\-06\-26T13:39:24.697401384+02:00",
|
|
"data": {
|
|
"errors": [
|
|
{
|
|
"error": "open /Users/jb/src/github.com/syncthing/syncthing/test/s2/h2j/.syncthing.aslkjd.tmp: permission denied",
|
|
"path": "h2j/aslkjd"
|
|
}
|
|
],
|
|
"folder": "default"
|
|
}
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
New in version 0.11.12.
|
|
|
|
.sp
|
|
\fBSEE ALSO:\fP
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
The statechanged event.
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS FolderRejected
|
|
.sp
|
|
Emitted when a device sends index information for a folder we do not
|
|
have, or have but do not share with the device in question.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
"id": 27,
|
|
"type": "FolderRejected",
|
|
"time": "2014\-08\-19T10:41:06.761751399+02:00",
|
|
"data": {
|
|
"device": "EJHMPAQ\-OGCVORE\-ISB4IS3\-SYYVJXF\-TKJGLTU\-66DIQPF\-GJ5D2GX\-GQ3OWQK",
|
|
"folder": "unique"
|
|
}
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS FolderSummary
|
|
.sp
|
|
The FolderSummary event is emitted when folder contents have changed
|
|
locally. This can be used to calculate the current local completion
|
|
state.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
"id": 16,
|
|
"type": "FolderSummary",
|
|
"time": "2015\-04\-17T14:12:20.460121585+09:00",
|
|
"data": {
|
|
"folder": "default",
|
|
"summary": {
|
|
"globalBytes": 0,
|
|
"globalDeleted": 0,
|
|
"globalFiles": 0,
|
|
"ignorePatterns": false,
|
|
"inSyncBytes": 0,
|
|
"inSyncFiles": 0,
|
|
"invalid": "",
|
|
"localBytes": 0,
|
|
"localDeleted": 0,
|
|
"localFiles": 0,
|
|
"needBytes": 0,
|
|
"needFiles": 0,
|
|
"state": "idle",
|
|
"stateChanged": "2015\-04\-17T14:12:12.455224687+09:00",
|
|
"version": 0
|
|
}
|
|
}
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS ItemFinished
|
|
.sp
|
|
Generated when Syncthing ends synchronizing a file to a newer version. A
|
|
successful operation:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
"id": 93,
|
|
"type": "ItemFinished",
|
|
"time": "2014\-07\-13T21:22:03.414609034+02:00",
|
|
"data": {
|
|
"item": "test.txt",
|
|
"folder": "default",
|
|
"error": null,
|
|
"type": "file",
|
|
"action": "update"
|
|
}
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
An unsuccessful operation:
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
"id": 44,
|
|
"type": "ItemFinished",
|
|
"time": "2015\-05\-27T11:21:05.711133004+02:00",
|
|
"data": {
|
|
"action": "update",
|
|
"error": "open /Users/jb/src/github.com/syncthing/syncthing/test/s2/foo/.syncthing.hej.tmp: permission denied",
|
|
"folder": "default",
|
|
"item": "foo/hej",
|
|
"type": "file"
|
|
}
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
The \fBaction\fP field is either \fBupdate\fP (contents changed), \fBmetadata\fP (file metadata changed but not contents), or \fBdelete\fP\&.
|
|
.sp
|
|
New in version 0.11.10: The \fBmetadata\fP action.
|
|
|
|
.SS ItemStarted
|
|
.sp
|
|
Generated when Syncthing begins synchronizing a file to a newer version.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
"id": 93,
|
|
"type": "ItemStarted",
|
|
"time": "2014\-07\-13T21:22:03.414609034+02:00",
|
|
"data": {
|
|
"item": "test.txt",
|
|
"folder": "default",
|
|
"type": "file",
|
|
"action": "update"
|
|
}
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
The \fBaction\fP field is either \fBupdate\fP (contents changed), \fBmetadata\fP (file metadata changed but not contents), or \fBdelete\fP\&.
|
|
.sp
|
|
New in version 0.11.10: The \fBmetadata\fP action.
|
|
|
|
.SS LocalIndexUpdated
|
|
.sp
|
|
Generated when the local index information has changed, due to
|
|
synchronizing one or more items from the cluster or discovering local
|
|
changes during a scan.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
"id": 59,
|
|
"type": "LocalIndexUpdated",
|
|
"time": "2014\-07\-17T13:27:28.051369434+02:00",
|
|
"data": {
|
|
"folder": "default",
|
|
"items": 1000,
|
|
}
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS Ping
|
|
.sp
|
|
The Ping event is generated automatically every 60 seconds. This means
|
|
that even in the absence of any other activity, the event polling HTTP
|
|
request will return within a minute.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
"id": 46,
|
|
"type": "Ping",
|
|
"time": "2014\-07\-13T21:13:18.502171586+02:00",
|
|
"data": null
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS RemoteIndexUpdated
|
|
.sp
|
|
Generated each time new index information is received from a device.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
"id": 44,
|
|
"type": "RemoteIndexUpdated",
|
|
"time": "2014\-07\-13T21:04:35.394184435+02:00",
|
|
"data": {
|
|
"device": "NFGKEKE\-7Z6RTH7\-I3PRZXS\-DEJF3UJ\-FRWJBFO\-VBBTDND\-4SGNGVZ\-QUQHJAG",
|
|
"folder": "lightroom",
|
|
"items": 1000
|
|
}
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS Starting
|
|
.sp
|
|
Emitted exactly once, when Syncthing starts, before parsing
|
|
configuration etc.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
"id": 1,
|
|
"type": "Starting",
|
|
"time": "2014\-07\-17T13:13:32.044470055+02:00",
|
|
"data": {
|
|
"home": "/home/jb/.config/syncthing"
|
|
}
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS StartupCompleted
|
|
.sp
|
|
Emitted exactly once, when initialization is complete and Syncthing is
|
|
ready to start exchanging data with other devices.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
"id": 1,
|
|
"type": "StartupComplete",
|
|
"time": "2014\-07\-13T21:03:18.383239179+02:00",
|
|
"data": null
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS StateChanged
|
|
.sp
|
|
Emitted when a folder changes state. Possible states are \fBidle\fP,
|
|
\fBscanning\fP, \fBcleaning\fP and \fBsyncing\fP\&. The field \fBduration\fP is
|
|
the number of seconds the folder spent in state \fBfrom\fP\&. In the example
|
|
below, the folder \fBdefault\fP was in state \fBscanning\fP for 0.198
|
|
seconds and is now in state \fBidle\fP\&.
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
{
|
|
"id": 8,
|
|
"type": "StateChanged",
|
|
"time": "2014\-07\-17T13:14:28.697493016+02:00",
|
|
"data": {
|
|
"folder": "default",
|
|
"from": "scanning",
|
|
"duration": 0.19782869900000002,
|
|
"to": "idle"
|
|
}
|
|
}
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SH AUTHOR
|
|
The Syncthing Authors
|
|
.SH COPYRIGHT
|
|
2015, The Syncthing Authors
|
|
.\" Generated by docutils manpage writer.
|
|
.
|