The following terms are defined within the ND-Bus specification:
The term service is of central relevance within the ND-Bus terminology. A service is something that does something, provides some functionality to something else and may make use of the functionality of something else.
ND-Bus is about connecting services.
Todays operating systems encapsulate certain functionality within applications. The term service is more abstract. ND-Bus does not know about applications. So it depends on the implementation what part of computer software offers a ND-Bus service. Normally it is an application that will provide exactely one service, but of course is also possible that an application or that something else, e.g. a simple microcontroller firmware without an OS or the kernel of an OS, offers one or more services.
In ND-Bus services are hierarchically organized. On top is a mesh of domains. Domain is an abstraction for an organizational unit. With nowadays computers a domain normally includes exactely one operating system instance. Within a domain the next organizational unit are the users. Users can be anything, normally they are the people who use the OS (Unix/Windows user). On the next level there are the servicegroups that bundle services on arbitrary criterions. E.g. all services that belong to a particular desktop session are grouped together or all services that belong to the OS kernel. The next level are the services themselves. So: every service belongs to exactely one domain, exectely one user and exectely one servicegroup. If multiple servicegroups bundle the same kind of services those servicegroups can have same name, but they can still be differentiated by their unique instance identifiers. This is analogous with service that provide the same functionality.
Hierarchy (loose notation)
Every service within ND-Bus can play exactely one role. An ordinary service (e.g. mediaplayer, terminal emulator, webbrowser) has the role customer. But within every domain there must be exectely one service in the role of the agent. This one mainly acts as a broker to help the customers to connect to each other. One can see if a service is agent or customer by its name: An agent is always service "org.ndbus.agent" (with instance identifier 0) within user "ndbus" and servicegroup "ndbus" (with instance identifier 0).
Example domain (loose notation)
Like already stated, service provide functionality. This includes methods, signals and data represented as files. All these are again hierarchically organized within a service. This hierarchy is a tree. Within the tree there are containers called nodes. A node can again contain nodes and other things: files and interfaces. An interface is an abstraction similar to objects in object-oriented programming languages. Interfaces can contain methods and signals.
The various names in ND-Bus have some restrictions:
([A-Za-z_]+[A-Za-z0-9_]*)(\.([A-Za-z_]+[A-Za-z0-9_]*))* [A-Za-z_]+[A-Za-z0-9_]* [A-Za-z_]+[A-Za-z0-9_]* In various places the ND-Bus specification refers to particular data types, e.g. in the context of message formats. Especially can methods and signals only use a limited set of specific types as parameters. It is not possible to use other types than listed below, but with List<Variant> and Map<String, Variant> one can construct arbitrarily complex data structures of the given types.
| Conventinal name | Description |
|---|---|
All the things named before, means: domains, users, servicegroups, services, nodes, files, interfaces, methods and signals, are generally refered to as "entities" to make it easier to talk about them.
An entity is described by a combination of a classifier, name and parameters. The combination is the signature of the entity. The signature is a STRING formated as: <classifer>;<name>(;<parameter>)*. The number and format of the parameters and depend on the classifier. Every kind of entity has a unique classifier.
Classifiers are of type UINT8 and must be given in their decimal representations with no leading zeros.
| Conventional name | Decimal value |
|---|---|
| DOMAIN | 0 |
| USER | 1 |
| SERVICEGROUP | 2 |
| SERVICE | 3 |
| NODE | 4 |
| FILE | 5 |
| INTERFACE | 6 |
| METHOD | 7 |
| SIGNAL | 8 |
As stated before, entity signatures may include zero or more parameters. The number of parameters is fixed for a given classifier.
UINT32 and must be given in its decimal representation with no leading zeros. In some context the the parameter may be left blank (empty string). UINT32 and must be given in its decimal representation with no leading zeros. In some context the the parameter may be left blank (empty string). /|(/<name>)+, where <name> is a valid node name, but not "/". (<type>=<param>)+(,<type>=<param>)*, where <type> is a valid type name and <param> is a valid method parameter name. A parameter can be left blank (empty string) to indicate an empty parameter list. Has as parameter the list of the output parameters of the signal. The parameters uses the format: (<type>=<param>)+(,<type>=<param>)*, where <type> is a valid type name and <param> is a valid method parameter name. The parameter can be left blank (empty string) to indicate an empty parameter list.
The combination of domain, user, servicegroup and service uniquely identifies a service within ND-Bus. Nodes, files, interfaces, methods and signals are parts of a particular service and thus are organized in a tree structure. A particular entitiy can be refered to either by its complete identifier or by its short identifier which omits domain, user, servicegroup and service. Which identifier can be used depends on the context. Such an identifier is a sequence of ":"-separeted signatures defining the position of an entity within a ND-Bus system, starting from the domain.
Examples for complete identifiers:
Node: 0;local.alice:1;peter:2;kdesession;0:3;org.kde.amarok,0:4;control;/app/main
Root node: 0;local.alice:1;peter:2;kdesession;0:3;org.kde.amarok,0:4;/;
Method: 0;local.bob:1;peter:2;kde;0:3;org.app,0:4;/;:6;org.nice:7;doIt;;
Service: 0;local.bob:1;peter:2;terminal;0:3;cc.funny.tool;1337
Domain: 0;org.ndbus
Same examples for short identifiers:
Node: 4;control;/app/main
Root node: 4;/;
Method: 7;doIt;;
Service: not applicable
Domain: not applicable
Services talk to each other via sockets. The ND-Bus specification describes 3 different kinds of sockets that services may use as transport mechanism:
All ND-Bus communication is point-to-point so there is no need for addressing information within messages. The message is the smallest logical entity within the protocol. Every message belongs to a single transmission. Within each transmission each message has a unique message sequence number (MSN). Within each connection each transmission has a unique transmission sequence number (TSN). The message size (MS) indicated the number of bytes of the whole encoded message (including the size information itself). MS, TSN, MSN and MT form the message header (MH). All contents of a message must be encoded in the ND-Bus DataStream format.
| Field index | Type | Description |
|---|---|---|
| 0 | UINT32 | Message size |
| 1 | UINT32 | Transmission sequence number |
| 2 | UINT32 | Message sequence number |
| 3 | UINT32 | Message type |
The MH may be followed by the payload of the message. If a message contains any payload and how it is formatted depends on the message type (MT):
| Conventional name | Decimal value | Description |
|---|---|---|
ERROR | 0 | Error reply |
METHOD | 1 | Method call |
METHOD_RETURN | 2 | Method reply with returned data |
FILE | 3 | File request |
FILE_PART | 4 | Reply to file request with part of file |
FILE_ACK | 5 | Reception of file part acknowleged (if part left: ready for next) |
AUTH | 6 | Authentication request for previously requested action |
AUTH_RETURN | 7 | Authentication reply |
SIGNAL_SUBSCRIBE | 8 | Signal subscription request |
SIGNAL_ACK | 9 | Signal subscription reply |
SIGNAL | 10 | Signal emission |
| Field index | Type | Description |
|---|---|---|
| 0 | UINT32 | Error code (depends on context) |
| 1 | STRING | Error message (depends on context) |
| Field index | Type | Description |
|---|---|---|
| 0 | STRING | Node |
| 1 | STRING | Interface |
| 2 | STRING | Method |
| 3 | VARIANTLIST | Input |
| Field index | Type | Description |
|---|---|---|
| 0 | VARIANTLIST | Output |
| Field index | Type | Description |
|---|---|---|
| 0 | STRING | Node |
| 1 | STRING | File |
| Field index | Type | Description |
|---|---|---|
| 0 | UINT32 | Parts left (last part: 0) |
| 1 | BYTEARRAY | Part of file |
This message type contains no payload.
| Field index | Type | Description |
|---|---|---|
| 0 | BYTEARRAY | Chunck as challenge for authentication procedure |
| Field index | Type | Description |
|---|---|---|
| 0 | BYTEARRAY | Returned chunck of authentication procedure |
| Field index | Type | Description |
|---|---|---|
| 0 | STRING | Node |
| 1 | STRING | Interface |
| 2 | STRING | Signal |
This message type contains no payload.
| Field index | Type | Description |
|---|---|---|
| 0 | STRING | Node |
| 1 | STRING | Interface |
| 2 | STRING | Signal |
| 3 | VARIANTLIST | Output |
Daemon A of local.alice wants to connect to daemon B of local.bob.
/:org.ndbus:hello on B /:org.ndbus:authenticate on B /:org.ndbus.daemon.daemons:connectDomains on B 
Connecting daemon to daemon
Process P wants to connect to daemon A of local.alice A and become a service.
/:org.ndbus:hello on A /:org.ndbus:authenticate on A /:org.ndbus.daemon.services:joinDomain on A /:org.ndbus.daemon.services:joinUser on A /:org.ndbus.daemon.services:joinServiceGroup on A /:org.ndbus.daemon.services:addService on A 
Connecting service to daemon
Service A at daemon DA on local.alice wants to connect to service B at daemon DB on local.bob.
/:org.ndbus.daemon.services:broker on DA (and thus asks for e.g. domain="local.bob", user="system",servicegroup="system",service="org.kernel.acpi") /:org.ndbus.daemon.daemons:broker on DB /:org.ndbus:hello on B (and thus identifies itself e.g. as domain="local.alice", user="barne",servicegroup="kdesession,0",service="cc.chubbyblackcat.funnyremotetool") /:org.ndbus.authenticate on B /:org.ndbus.daemon.services:broker on DB /:org.ndbus.service.services:connectServices on B (as this commands needs authentication, on success A and B now both are authenticated against each other (using S). 
Connecting service to service
1.7.1