# BLEServer Class

TBD.

## Syntax

```text
ipworksble.BLEServer
```

## Remarks

TBD.

## Property List

*The following is the full list of the properties of the class with short descriptions. Click on the links for further details.*

|  |  |
| --- | --- |
| [Listening](#listening-property-bleserver-class) | This property indicates whether the class is listening for incoming connections on LocalPort. |
| [ServerId](#serverid-property-bleserver-class) | TBD. |

## Method List

*The following is the full list of the methods of the class with short descriptions. Click on the links for further details.*

|  |  |
| --- | --- |
| [AddCharacteristic](#addcharacteristic-method-bleserver-class) | TBD. |
| [Config](#config-method-bleserver-class) | Sets or retrieves a configuration setting. |
| [DoEvents](#doevents-method-bleserver-class) | This method processes events from the internal message queue. |
| [StartListening](#startlistening-method-bleserver-class) | TBD. |
| [StopListening](#stoplistening-method-bleserver-class) | TBD. |

## Event List

*The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.*

|  |  |
| --- | --- |
| [AdvertisementStatusChanged](#advertisementstatuschanged-event-bleserver-class) | TBD. |
| [Connected](#connected-event-bleserver-class) | TBD. |
| [Disconnected](#disconnected-event-bleserver-class) | TBD. |
| [Error](#error-event-bleserver-class) | Fired when information is available about errors during data delivery. |
| [Log](#log-event-bleserver-class) | Fires once for each log message. |
| [ReadRequested](#readrequested-event-bleserver-class) | TBD. |
| [SessionStatusChanged](#sessionstatuschanged-event-bleserver-class) | TBD. |
| [SubscriptionChanged](#subscriptionchanged-event-bleserver-class) | TBD. |
| [WriteRequested](#writerequested-event-bleserver-class) | TBD. |

## Config Settings

*The following is a list of config settings for the class with short descriptions. Click on the links for further details.*

|  |  |
| --- | --- |
| [LogLevel](#LogLevel) | The level of detail that is logged. |
| [BuildInfo](#BuildInfo) | Information about the product's build. |
| [GUIAvailable](#GUIAvailable) | Whether or not a message loop is available for processing events. |
| [LicenseInfo](#LicenseInfo) | Information about the current license. |
| [MaskSensitiveData](#MaskSensitiveData) | Whether sensitive data is masked in log messages. |
| [UseDaemonThreads](#UseDaemonThreads) | Whether threads created by the class are daemon threads. |
| [UseInternalSecurityAPI](#UseInternalSecurityAPI) | Whether or not to use the system security libraries or an internal implementation. |
| [UseVirtualThreads](#UseVirtualThreads) | Whether threads created by the class use virtual threads instead of platform threads. |

# Listening Property ([BLEServer](#bleserver-class) Class)

This property indicates whether the class is listening for incoming connections on LocalPort.

## Syntax

```text
public boolean isListening();
```

## Default Value

False

## Remarks

This property indicates whether the class is listening for connections on the port specified by the LocalPort property. Use the [StartListening](#startlistening-method-bleserver-class) and [StopListening](#stoplistening-method-bleserver-class) methods to control whether the class is listening.

This property is read-only and not available at design time.

# ServerId Property ([BLEServer](#bleserver-class) Class)

TBD.

## Syntax

```text
public String getServerId();
public void setServerId(String serverId);
```

## Default Value

""

## Remarks

TBD.

This property is not available at design time.

# AddCharacteristic Method ([BLEServer](#bleserver-class) Class)

TBD.

## Syntax

```text
public void addCharacteristic(String serviceId, String characteristicId, int props);
```

## Remarks

TBD.

# Config Method ([BLEServer](#bleserver-class) Class)

Sets or retrieves a configuration setting.

## Syntax

```text
public String config(String configurationString);
```

## Remarks

Config is a generic method available in every class. It is used to set and retrieve [configuration settings](#config-settings-bleserver-class) for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these *internal properties* is provided through the Config method.

To set a configuration setting named *PROPERTY*, you must call *Config("PROPERTY=VALUE")*, where *VALUE* is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a [configuration setting](#config-settings-bleserver-class), you must call *Config("PROPERTY")*. The value will be returned as a string.

# DoEvents Method ([BLEServer](#bleserver-class) Class)

This method processes events from the internal message queue.

## Syntax

```text
public void doEvents();
```

## Remarks

When DoEvents is called, the class processes any available events. If no events are available, it waits for a preset period of time, and then returns.

# StartListening Method ([BLEServer](#bleserver-class) Class)

TBD.

## Syntax

```text
public void startListening(String serviceId);
```

## Remarks

TBD.

# StopListening Method ([BLEServer](#bleserver-class) Class)

TBD.

## Syntax

```text
public void stopListening(String serviceId);
```

## Remarks

TBD.

# AdvertisementStatusChanged Event ([BLEServer](#bleserver-class) Class)

TBD.

## Syntax

```text
public class DefaultBLEServerEventListener implements BLEServerEventListener {
  ...
  public void advertisementStatusChanged(BLEServerAdvertisementStatusChangedEvent e) {}
  ...
}

public class BLEServerAdvertisementStatusChangedEvent {
  public int status;
  public int error;
}
```

## Remarks

TBD.

# Connected Event ([BLEServer](#bleserver-class) Class)

TBD.

## Syntax

```text
public class DefaultBLEServerEventListener implements BLEServerEventListener {
  ...
  public void connected(BLEServerConnectedEvent e) {}
  ...
}

public class BLEServerConnectedEvent {
  public String clientId;
  public int statusCode;
  public String description;
}
```

## Remarks

TBD.

# Disconnected Event ([BLEServer](#bleserver-class) Class)

TBD.

## Syntax

```text
public class DefaultBLEServerEventListener implements BLEServerEventListener {
  ...
  public void disconnected(BLEServerDisconnectedEvent e) {}
  ...
}

public class BLEServerDisconnectedEvent {
  public String clientId;
  public int statusCode;
  public String description;
}
```

## Remarks

TBD.

# Error Event ([BLEServer](#bleserver-class) Class)

Fired when information is available about errors during data delivery.

## Syntax

```text
public class DefaultBLEServerEventListener implements BLEServerEventListener {
  ...
  public void error(BLEServerErrorEvent e) {}
  ...
}

public class BLEServerErrorEvent {
  public int errorCode;
  public String description;
}
```

## Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the class throws an exception.

The *ErrorCode* parameter contains an error code, and the *Description* parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the [Error Codes](#trappable-errors-bleserver-class) section.

# Log Event ([BLEServer](#bleserver-class) Class)

Fires once for each log message.

## Syntax

```text
public class DefaultBLEServerEventListener implements BLEServerEventListener {
  ...
  public void log(BLEServerLogEvent e) {}
  ...
}

public class BLEServerLogEvent {
  public int logLevel;
  public String message;
  public String logType;
}
```

## Remarks

This events fires once for each log message generated by the class. The verbosity is controlled by the [LogLevel](#LogLevel) setting.

*LogLevel* indicates the level of the *Message*. Possible values are:

|  |  |
| --- | --- |
| 0 (None) | No events are logged. |
| 1 (Info - default) | Informational events are logged. |
| 2 (Verbose) | Detailed data is logged. |
| 3 (Debug) | Debug data is logged. |

The default log level, Info, provides information when most BLE operations begin and end, and should be sufficient to get a good idea of what the class is doing at a high level.

The Verbose log level adds a few extra operation timing messages, and adds more detail to some messages logged at the Info level.

The Debug log level causes the class to output as much information as possible about what it is doing at all times. All BLE communications, even those which are typically abstracted away by the API, are logged in full detail. Typically the additional information added by this log level is not helpful to the end user, and would only be necessary to capture if you wish to report an issue to the support team.

*LogType* identifies the type of log entry. Possible values are:

- Scanning: Messages relating to scanning and advertisements.
- Connection: Messages relating to connecting, disconnecting, and connection failures.
- Discovery: Messages relating to any service, characteristic, or descriptor discovery process.
- Read: Messages relating to reading values from the remote device.
- Write: Messages relating to writing values to the remote device.
- Subscriptions: Messages relating to subscribing to and unsubscribing from characteristics.
- Info, Verbose, and Debug: Miscellaneous messages fired at the applicable log level concerning internal class operations.

# ReadRequested Event ([BLEServer](#bleserver-class) Class)

TBD.

## Syntax

```text
public class DefaultBLEServerEventListener implements BLEServerEventListener {
  ...
  public void readRequested(BLEServerReadRequestedEvent e) {}
  ...
}

public class BLEServerReadRequestedEvent {
  public String clientId;
  public String serviceId;
  public String characteristicId;
  public String responseValue; //read-write
  public boolean accept; //read-write
}
```

## Remarks

TBD.

# SessionStatusChanged Event ([BLEServer](#bleserver-class) Class)

TBD.

## Syntax

```text
public class DefaultBLEServerEventListener implements BLEServerEventListener {
  ...
  public void sessionStatusChanged(BLEServerSessionStatusChangedEvent e) {}
  ...
}

public class BLEServerSessionStatusChangedEvent {
  public String clientId;
  public int status;
  public int error;
}
```

## Remarks

TBD.

# SubscriptionChanged Event ([BLEServer](#bleserver-class) Class)

TBD.

## Syntax

```text
public class DefaultBLEServerEventListener implements BLEServerEventListener {
  ...
  public void subscriptionChanged(BLEServerSubscriptionChangedEvent e) {}
  ...
}

public class BLEServerSubscriptionChangedEvent {
  public String serviceId;
  public String characteristicId;
  public boolean isSubscribed;
}
```

## Remarks

TBD.

# WriteRequested Event ([BLEServer](#bleserver-class) Class)

TBD.

## Syntax

```text
public class DefaultBLEServerEventListener implements BLEServerEventListener {
  ...
  public void writeRequested(BLEServerWriteRequestedEvent e) {}
  ...
}

public class BLEServerWriteRequestedEvent {
  public String clientId;
  public String serviceId;
  public String characteristicId;
  public byte[] value;
  public boolean withResponse;
  public boolean accept; //read-write
}
```

## Remarks

TBD.

# Config Settings ([BLEServer](#bleserver-class) Class)

 The class accepts one or more of the following *configuration settings*. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these *internal properties* is provided through the [Config](#config-method-bleserver-class) method.

### BLEServer Config Settings

**LogLevel**: The level of detail that is logged.This setting controls the level of detail that is logged through the [Log](#log-event-bleserver-class) event. Possible values are:

|  |  |
| --- | --- |
| 0 (None) | No events are logged. |
| 1 (Info - default) | Informational events are logged. |
| 2 (Verbose) | Detailed data is logged. |
| 3 (Debug) | Debug data is logged. |

The default log level, Info, provides information when most BLE operations begin and end, and should be sufficient to get a good idea of what the class is doing at a high level.

The Verbose log level adds a few extra operation timing messages, and adds more detail to some messages logged at the Info level.

The Debug log level causes the class to output as much information as possible about what it is doing at all times. All BLE communications, even those which are typically abstracted away by the API, are logged in full detail. Typically the additional information added by this log level is not helpful to the end user, and would only be necessary to capture if you wish to report an issue to the support team.

### Base Config Settings

**BuildInfo**: Information about the product's build.When queried, this setting will return a string containing information about the product's build.

**GUIAvailable**: Whether or not a message loop is available for processing events.In a GUI-based application, long-running blocking operations may cause the application to stop responding to input until the operation returns. The class will attempt to discover whether or not the application has a message loop and, if one is discovered, it will process events in that message loop during any such blocking operation.

In some non-GUI applications, an invalid message loop may be discovered that will result in errant behavior. In these cases, setting [GUIAvailable](#GUIAvailable) to *false* will ensure that the class does not attempt to process external events.

**LicenseInfo**: Information about the current license.When queried, this setting will return a string containing information about the license this instance of a class is using. It will return the following information:

- Product: The product the license is for.
- Product Key: The key the license was generated from.
- License Source: Where the license was found (e.g., RuntimeLicense, License File).
- License Type: The type of license installed (e.g., Royalty Free, Single Server).
- Last Valid Build: The last valid build number for which the license will work.

**MaskSensitiveData**: Whether sensitive data is masked in log messages.In certain circumstances it may be beneficial to mask sensitive data, like passwords, in log messages. Set this to *true* to mask sensitive data. The default is *true*.

**UseDaemonThreads**: Whether threads created by the class are daemon threads.If set to True (default), when the class creates a thread, the thread's Daemon property will be explicitly set to True. When set to False, the class will not set the Daemon property on the created thread. The default value is True.

**UseInternalSecurityAPI**: Whether or not to use the system security libraries or an internal implementation. When set to *false*, the class will use the system security libraries by default to perform cryptographic functions where applicable.

Setting this configuration setting to *true* tells the class to use the internal implementation instead of using the system security libraries.

 This setting is set to *false* by default on all platforms.

**UseVirtualThreads**: Whether threads created by the class use virtual threads instead of platform threads.If set to *true*, when the class creates a thread, it will be created as a virtual thread instead of a platform thread. Virtual threads are lightweight threads managed by the JVM that are multiplexed onto a small pool of carrier threads, significantly reducing memory usage and platform thread count under high-concurrency workloads. Requires Java 24 or later. The default value is *false*.

# Trappable Errors ([BLEServer](#bleserver-class) Class)

### BLEServer Errors

|  |  |
| --- | --- |
| 600 | Invalid UUID. |
| 601 | Invalid Id. |
| 602 | Action not allowed. See error message for more details. |
| 603 | Scanning error. See error message for more details. |
| 604 | Connection error. See error message for more details. |
| 605 | Must be connected to a device to perform the requested action. |
| 606 | Error during communication. See error message for more details. |
| 607 | Device unreachable during communication attempt. |
| 608 | Error during discovery. See error message for more details. |
| 609 | Class detected a cycle of included services. |
| 610 | General read error. See error message for more details. |
| 611 | General write error. See error message for more details. |
| 612 | Application-specific protocol error. This error code indicates that a protocol error code in the range 0x80-0x9F was returned during a BLE communication. Such error codes are reserved for applications to use as they see fit. Refer to the documentation of your remote device for more information. |
| 613 | Bluetooth low energy not supported. |
| 701 | Invalid Handle: The attribute handle given was not valid on this server. |
| 702 | Read Not Permitted: The attribute cannot be read due to its permissions. |
| 703 | Write Not Permitted: The attribute cannot be written due to its permissions. |
| 704 | Invalid PDU: The attribute PDU was invalid. |
| 705 | Insufficient Authentication: The attribute requires authentication before it can be read or written. |
| 706 | Request Not Supported: Attribute server does not support the request received from the client. |
| 707 | Invalid Offset: Offset specified was past the end of the attribute's value. |
| 708 | Insufficient Authorization: The attribute requires authorization before it can be read or written. |
| 709 | Prepare Queue Full: Too many prepare writes have been queued. |
| 710 | Attribute Not Found: No attribute found within the given attribute handle range. |
| 711 | Attribute Not Long: The attribute cannot be read or written using the Read Blob Request. |
| 712 | Insufficient Encryption Key Size: The Encryption Key Size used for encrypting this link is insufficient. |
| 713 | Invalid Attribute Value Length: The attribute value length is invalid for the operation. |
| 714 | Unlikely Error: The attribute request that was requested has encountered an error that was unlikely, and therefore could not be completed as requested. |
| 715 | Insufficient Encryption: The attribute requires encryption before it can be read or written. |
| 716 | Unsupported Group Type: The attribute type is not a supported grouping attribute as defined by a higher layer specification. |
| 717 | Insufficient Resources: Insufficient Resources to complete the request. |
| 952 | Write Request Rejected: A requested write operation could not be fulfilled for reasons other than its permissions. |
| 953 | Client Characteristic Configuration Descriptor (CCCD) Improperly Configured: The CCCD is not configured according to the requirements of the profile or service. |
| 954 | Procedure Already in Progress: A profile or service request cannot be serviced because a previously triggered operation is still in progress. |
| 955 | Out of Range: An attribute value is out of range (as defined by a profile or service specification). |