From 4392fbd3d96e2eea0d91f0eb9fd059ab38255986 Mon Sep 17 00:00:00 2001 From: Johan Hedberg Date: Mon, 26 Nov 2007 13:41:36 +0000 Subject: Update API descriptions to match new error codes --- hcid/dbus-api.txt | 117 +++++++++++++++++++++++++++++------------------- input/input-api.txt | 27 ++++++----- network/network-api.txt | 46 +++++++++---------- serial/serial-api.txt | 49 ++++++++++---------- 4 files changed, 132 insertions(+), 107 deletions(-) diff --git a/hcid/dbus-api.txt b/hcid/dbus-api.txt index 9a29916d..51a2eff7 100644 --- a/hcid/dbus-api.txt +++ b/hcid/dbus-api.txt @@ -51,84 +51,111 @@ Error hierarchy Interface org.bluez.Error -Errors Failed +Shared Errors (Can be thrown by hcid or any bluetooth service) + + DeviceUnreachable + + The remote device is either powered down or out of range. - An unknown error occured. The error messages is - taken from the strerror(errno) function. + AlreadyConnected + A connection request has been received on an already + connected device. - InvalidArguments + ConnectionAttemptFailed - Error returned when the argument list is invalid or - out of specification for the method. + An unexpected error (other than DeviceUnreachable) error + has occured while attempting a connection to a device. - NotAuthorized + NotConnected + The remote device is not connected, while the method call + would expect it to be, or is not in the expected state to + perform the action. - Error returned when the caller of a method is not - authorized. This might happen if a caller tries to - terminate a connection that it hasn't created. + InProgress + + Error returned if an operation is in progress. Since + this is a generic error that can be used in various + situations, the error message should be more clear + about what is in progress. For example "Bonding in + progress". + + InvalidArguments + + The DBUS request does not contain the right number of + arguments with the right type, or the arguments are there + but their value is wrong, or does not makes sense in the + current context. OutOfMemory Error returned when a memory allocation via malloc() fails. This error is similar to ENOMEM. - NoSuchAdapter + NotAvailable - Error returned when the requested adapter doesn't - exists. This error is similar to ENODEV. + Error returned when a specified record is not + available. - NotReady + NotSupported + + The remote device does not support the expected + feature. - Error returned when the adapter is DOWN. + AlreadyExists + One of the requested elements already exists - NotAvailable + DoesNotExist + One of the requested elements does not exist - Error returned when a specified record is not - available. + Canceled + The operation was canceled. - NotConnected + Failed - Error returned when the remote device isn't connected - at the moment. + This is a the most generic error. + It is thrown when something unexpected happens. - ConnectionAttemptFailed - AlreadyExists +Hcid specific Errors (Can be thrown by hcid only) - Error returned if a record for a specific procedure - already exists and it has been tried create a new - one. The error message however should indicate the - procedure that fails. For example "Bonding already - exists" + NotReady - DoesNotExist + Error returned when the adapter is DOWN. - Error returned if a record for a specifc procedure - doesn't exist. The error message however should - indicate the procedure that fails. For example - "Bonding does not exist". + UnknwownMethod + + This is an experimental method. - InProgress + NotAuthorized - Error returned if an operation is in progress. Since - this is a generic error that can be used in various - situations, the error message should be more clear - about what is in progress. For example "Bonding in - progress". + Error returned when the caller of a method is not + authorized. This might happen if a caller tries to + terminate a connection that it hasn't created. - NotSupported - The feature is not supported by the remote device + Rejected - AuthenticationFailed + NoSuchAdapter - AuthenticationTimeout + Error returned when the requested adapter doesn't + exists. This error is similar to ENODEV. - AuthenticationRejected + NoSuchService + + RequestDeferred + + NotInProgress + + UnsupportedMajorClass AuthenticationCanceled - UnsupportedMajorClass + AuthenticationFailed + + AuthenticationTimeout + + AuthenticationRejected + RepeatedAttempts Manager hierarchy ================= diff --git a/input/input-api.txt b/input/input-api.txt index 1d9fec1f..8eb13126 100644 --- a/input/input-api.txt +++ b/input/input-api.txt @@ -21,10 +21,10 @@ Methods array{string} ListDevices() On success it will return the path of the newly created device object. - Possible errors: org.bluez.input.AlreadyExists - org.bluez.input.NotSupported - org.bluez.input.ConnectionAttemptFailed - org.bluez.input.Failed + Possible errors: org.bluez.Error.AlreadyExists + org.bluez.Error.NotSupported + org.bluez.Error.ConnectionAttemptFailed + org.bluez.Error.Failed string CreateSecureDevice(string address) @@ -34,18 +34,17 @@ Methods array{string} ListDevices() On success it will return the path of the newly created device object. - Possible errors: org.bluez.input.AlreadyExists - org.bluez.input.NotSupported - org.bluez.input.ConnectionAttemptFailed - org.bluez.input.AuthenticationFailed - org.bluez.input.Failed + Possible errors: org.bluez.Error.AlreadyExists + org.bluez.Error.NotSupported + org.bluez.Error.ConnectionAttemptFailed + org.bluez.Error.Failed void RemoveDevice(string path) Remove the input device object for a given path. - Possible errors:org.bluez.input.DoesNotExist - org.bluez.input.Failed + Possible errors:org.bluez.Error.DoesNotExist + org.bluez.Error.Failed Signals void DeviceCreated(string path) @@ -90,14 +89,14 @@ Methods string GetAdapter() Connect to the input device. - Possible errors: org.bluez.input.AlreadyConnected - org.bluez.input.ConnectionAttemptFailed + Possible errors: org.bluez.Error.AlreadyConnected + org.bluez.Error.ConnectionAttemptFailed void Disconnect() Disconnect from the input device. - Possible errors: org.bluez.input.Failed + Possible errors: org.bluez.Error.Failed Signals void Connected() diff --git a/network/network-api.txt b/network/network-api.txt index e5916088..2d46abfd 100644 --- a/network/network-api.txt +++ b/network/network-api.txt @@ -19,24 +19,24 @@ Methods array{string} ListServers() Returns server path. - Possible errors: org.bluez.network.Error.DoesNotExist - org.bluez.network.Error.Failed + Possible errors: org.bluez.Error.DoesNotExist + org.bluez.Error.Failed string CreateConnection(string address, string uuid) Creates a network connection object(NAP or GN). - Possible errors: org.bluez.network.Error.AlreadyExists - org.bluez.network.Error.NotSupported - org.bluez.network.Error.ConnectionAttemptFailed - org.bluez.network.Error.Failed + Possible errors: org.bluez.Error.AlreadyExists + org.bluez.Error.NotSupported + org.bluez.Error.ConnectionAttemptFailed + org.bluez.Error.Failed void RemoveConnection(string path) Removes a network connection object for a given path. - Possible errors: org.bluez.network.Error.DoesNotExist - org.bluez.network.Error.Failed + Possible errors: org.bluez.Error.DoesNotExist + org.bluez.Error.Failed array{string} ListConnections() @@ -46,27 +46,27 @@ Methods array{string} ListServers() Returns connection path. - Possible errors: org.bluez.network.Error.DoesNotExist - org.bluez.network.Error.Failed + Possible errors: org.bluez.Error.DoesNotExist + org.bluez.Error.Failed string LastConnection() Returns last connected connection path, if none is connected fallback to last created connection. - Possible errors: org.bluez.network.Error.DoesNotExist + Possible errors: org.bluez.Error.DoesNotExist string DefaultConnection() Returns default connection path. - Possible errors: org.bluez.network.Error.DoesNotExist + Possible errors: org.bluez.Error.DoesNotExist string ChangeDefaultConnection(string pattern) Changes default connection path. - Possible errors: org.bluez.network.Error.DoesNotExist + Possible errors: org.bluez.Error.DoesNotExist Signals void ConnectionCreated(string path) @@ -90,14 +90,14 @@ Methods string GetUUID() Enable server and updates service record. - Possible errors: org.bluez.network.Error.AlreadyExists - org.bluez.network.Error.Failed + Possible errors: org.bluez.Error.AlreadyExists + org.bluez.Error.Failed void Disable() Disable server and remove service record. - Possible errors: org.bluez.network.Error.Failed + Possible errors: org.bluez.Error.Failed bool IsEnabled() @@ -151,40 +151,40 @@ Methods string GetAdapter() Returns the string representation of connected host. - Possible errors: org.bluez.network.Error.Failed + Possible errors: org.bluez.Error.Failed string GetDescription() Returns the string description of connected host. - Possible errors: org.bluez.network.Error.Failed + Possible errors: org.bluez.Error.Failed string GetInterface() Returns the string network interface. - Possible errors: org.bluez.network.Error.Failed + Possible errors: org.bluez.Error.Failed string Connect() Connects to host and return the network interface created. - Possible errors: org.bluez.network.Error.ConnectionAttemptFailed - org.bluez.network.Error.Failed + Possible errors: org.bluez.Error.ConnectionAttemptFailed + org.bluez.Error.Failed void CancelConnect() Abort connection attempt in case of errors or timeouts in the client. - Possible errors: org.bluez.network.Error.Failed + Possible errors: org.bluez.Error.Failed void Disconnect() Disconnects to host. - Possible errors: org.bluez.network.Error.Failed + Possible errors: org.bluez.Error.Failed bool IsConnected() diff --git a/serial/serial-api.txt b/serial/serial-api.txt index 5ff1dfd2..4730e6a5 100644 --- a/serial/serial-api.txt +++ b/serial/serial-api.txt @@ -20,32 +20,32 @@ Methods string CreateProxy(string uuid, string address) replacing the null byte by 'x00'. eg: "/dev/ttyS0", "/tmp/gps-data", "x00/org/bluez/echo". - Possible errors:org.bluez.serial.Error.InvalidArguments - org.bluez.serial.NotAvailable - org.bluez.serial.Failed + Possible errors:org.bluez.Error.InvalidArguments + org.bluez.Error.NotAvailable + org.bluez.Error.Failed void RemoveProxy(string path) [experimental] Removes the serial port proxy object for given path. - Possible errors:org.bluez.serial.Error.DoesNotExist + Possible errors:org.bluez.Error.DoesNotExist string CreatePort(string address, string pattern) [experimental] Creates a serial port object. - Possible errors:org.bluez.serial.Error.InvalidArguments - org.bluez.serial.Error.ConnectionCanceled - org.bluez.serial.Error.ConnectionInProgress - org.bluez.serial.Error.ConnectionAttemptFailed - org.bluez.serial.Error.NotSupported - org.bluez.serial.Error.Failed + Possible errors:org.bluez.Error.InvalidArguments + org.bluez.Error.Canceled + org.bluez.Error.InProgress + org.bluez.Error.ConnectionAttemptFailed + org.bluez.Error.NotSupported + org.bluez.Error.Failed void RemovePort(string path) [experimental] Removes the serial port object for given path. - Possible errors:org.bluez.serial.Error.DoesNotExist + Possible errors:org.bluez.Error.DoesNotExist array{string} ListPorts() [experimental] @@ -61,27 +61,26 @@ Methods string CreateProxy(string uuid, string address) remote device and then creates a RFCOMM TTY device for it. The RFCOMM TTY device is returned. - Possible errors:org.bluez.serial.Error.InvalidArguments - org.bluez.serial.Error.ConnectionCanceled - org.bluez.serial.Error.ConnectionInProgress - org.bluez.serial.Error.ConnectionAttemptFailed - org.bluez.serial.Error.NotSupported - org.bluez.serial.Error.Failed + Possible errors:org.bluez.Error.InvalidArguments + org.bluez.Error.Canceled + org.bluez.Error.InProgress + org.bluez.Error.ConnectionAttemptFailed + org.bluez.Error.NotSupported + org.bluez.Error.Failed void CancelConnectService(string address, string pattern) Cancel a previous ConnectService method call. - Possible errors:org.bluez.serial.Error.InvalidArguments - org.bluez.serial.Error.ConnectionNotInProgress + Possible errors:org.bluez.serial.InvalidArguments void DisconnectService(string device) Disconnect a RFCOMM TTY device that has been created via the ConnectService method. - Possible errors:org.bluez.serial.Error.InvalidArguments - org.bluez.serial.Error.DoesNotExist + Possible errors:org.bluez.Error.InvalidArguments + org.bluez.Error.DoesNotExist Signals void PortCreated(string path) [experimental] @@ -137,13 +136,13 @@ Methods: void Enable() [experimental] Register the serial proxy service record and start listenning on the specified adapter/channel. - Possible errors:org.bluez.serial.Error.Failed + Possible errors:org.bluez.Error.Failed void Disable() [experimental] Unregister the service record and stop listenning. - Possible errors:org.bluez.serial.Error.Failed + Possible errors:org.bluez.Error.Failed dict GetInfo() [experimental] Returns the proxy properties @@ -157,5 +156,5 @@ Methods: void Enable() [experimental] 6, 7 and 8. Available stop bits: 1 and 2. Available parity: "even", "odd", "mark", "space" and "none". - Possible errors:org.bluez.serial.Error.InvalidArguments - org.bluez.serial.Error.Failed + Possible errors:org.bluez.Error.InvalidArguments + org.bluez.Error.Failed -- cgit