# BLEServer Component

TBD.

## Syntax

```text
nsoftware.IPWorksBLE.BLEServer
```

## Remarks

TBD.

## Property List

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

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

## Method List

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

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

## Event List

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

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

## Config Settings

*The following is a list of config settings for the component 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. |
| [UseInternalSecurityAPI](#UseInternalSecurityAPI) | Whether or not to use the system security libraries or an internal implementation. |

# Listening Property ([BLEServer](#bleserver-component) Component)

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

## Syntax

```text
public bool Listening { get; }
```

## Default Value

False

## Remarks

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

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

# ServerId Property ([BLEServer](#bleserver-component) Component)

TBD.

## Syntax

```text
public string ServerId { get; set; }
```

## Default Value

""

## Remarks

TBD.

This property is not available at design time.

# AddCharacteristic Method ([BLEServer](#bleserver-component) Component)

TBD.

## Syntax

```text
public void AddCharacteristic(string serviceId, string characteristicId, int props);

Async Version
public async Task AddCharacteristic(string serviceId, string characteristicId, int props);
public async Task AddCharacteristic(string serviceId, string characteristicId, int props, CancellationToken cancellationToken);
```

## Remarks

TBD.

# Config Method ([BLEServer](#bleserver-component) Component)

Sets or retrieves a configuration setting.

## Syntax

```text
public string Config(string configurationString);

Async Version
public async Task<string> Config(string configurationString);
public async Task<string> Config(string configurationString, CancellationToken cancellationToken);
```

## Remarks

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

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, 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-component), you must call *Config("PROPERTY")*. The value will be returned as a string.

# DoEvents Method ([BLEServer](#bleserver-component) Component)

This method processes events from the internal message queue.

## Syntax

```text
public void DoEvents();

Async Version
public async Task DoEvents();
public async Task DoEvents(CancellationToken cancellationToken);
```

## Remarks

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

# StartListening Method ([BLEServer](#bleserver-component) Component)

TBD.

## Syntax

```text
public void StartListening(string serviceId);

Async Version
public async Task StartListening(string serviceId);
public async Task StartListening(string serviceId, CancellationToken cancellationToken);
```

## Remarks

TBD.

# StopListening Method ([BLEServer](#bleserver-component) Component)

TBD.

## Syntax

```text
public void StopListening(string serviceId);

Async Version
public async Task StopListening(string serviceId);
public async Task StopListening(string serviceId, CancellationToken cancellationToken);
```

## Remarks

TBD.

# AdvertisementStatusChanged Event ([BLEServer](#bleserver-component) Component)

TBD.

## Syntax

```text
public event OnAdvertisementStatusChangedHandler OnAdvertisementStatusChanged;

public delegate void OnAdvertisementStatusChangedHandler(object sender, BLEServerAdvertisementStatusChangedEventArgs e);

public class BLEServerAdvertisementStatusChangedEventArgs : EventArgs {
  public int Status { get; }
  public int Error { get; }
}
```

## Remarks

TBD.

# Connected Event ([BLEServer](#bleserver-component) Component)

TBD.

## Syntax

```text
public event OnConnectedHandler OnConnected;

public delegate void OnConnectedHandler(object sender, BLEServerConnectedEventArgs e);

public class BLEServerConnectedEventArgs : EventArgs {
  public string ClientId { get; }
  public int StatusCode { get; }
  public string Description { get; }
}
```

## Remarks

TBD.

# Disconnected Event ([BLEServer](#bleserver-component) Component)

TBD.

## Syntax

```text
public event OnDisconnectedHandler OnDisconnected;

public delegate void OnDisconnectedHandler(object sender, BLEServerDisconnectedEventArgs e);

public class BLEServerDisconnectedEventArgs : EventArgs {
  public string ClientId { get; }
  public int StatusCode { get; }
  public string Description { get; }
}
```

## Remarks

TBD.

# Error Event ([BLEServer](#bleserver-component) Component)

Fired when information is available about errors during data delivery.

## Syntax

```text
public event OnErrorHandler OnError;

public delegate void OnErrorHandler(object sender, BLEServerErrorEventArgs e);

public class BLEServerErrorEventArgs : EventArgs {
  public int ErrorCode { get; }
  public string Description { get; }
}
```

## Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the component 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-component) section.

# Log Event ([BLEServer](#bleserver-component) Component)

Fires once for each log message.

## Syntax

```text
public event OnLogHandler OnLog;

public delegate void OnLogHandler(object sender, BLEServerLogEventArgs e);

public class BLEServerLogEventArgs : EventArgs {
  public int LogLevel { get; }
  public string Message { get; }
  public string LogType { get; }
}
```

## Remarks

This events fires once for each log message generated by the component. 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 component 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 component 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 component operations.

# ReadRequested Event ([BLEServer](#bleserver-component) Component)

TBD.

## Syntax

```text
public event OnReadRequestedHandler OnReadRequested;

public delegate void OnReadRequestedHandler(object sender, BLEServerReadRequestedEventArgs e);

public class BLEServerReadRequestedEventArgs : EventArgs {
  public string ClientId { get; }
  public string ServiceId { get; }
  public string CharacteristicId { get; }
  public string ResponseValue { get; set; }
  public bool Accept { get; set; }
}
```

## Remarks

TBD.

# SessionStatusChanged Event ([BLEServer](#bleserver-component) Component)

TBD.

## Syntax

```text
public event OnSessionStatusChangedHandler OnSessionStatusChanged;

public delegate void OnSessionStatusChangedHandler(object sender, BLEServerSessionStatusChangedEventArgs e);

public class BLEServerSessionStatusChangedEventArgs : EventArgs {
  public string ClientId { get; }
  public int Status { get; }
  public int Error { get; }
}
```

## Remarks

TBD.

# SubscriptionChanged Event ([BLEServer](#bleserver-component) Component)

TBD.

## Syntax

```text
public event OnSubscriptionChangedHandler OnSubscriptionChanged;

public delegate void OnSubscriptionChangedHandler(object sender, BLEServerSubscriptionChangedEventArgs e);

public class BLEServerSubscriptionChangedEventArgs : EventArgs {
  public string ServiceId { get; }
  public string CharacteristicId { get; }
  public bool IsSubscribed { get; }
}
```

## Remarks

TBD.

# WriteRequested Event ([BLEServer](#bleserver-component) Component)

TBD.

## Syntax

```text
public event OnWriteRequestedHandler OnWriteRequested;

public delegate void OnWriteRequestedHandler(object sender, BLEServerWriteRequestedEventArgs e);

public class BLEServerWriteRequestedEventArgs : EventArgs {
  public string ClientId { get; }
  public string ServiceId { get; }
  public string CharacteristicId { get; }
  public string Value { get; }  public byte[] ValueB { get; }
  public bool WithResponse { get; }
  public bool Accept { get; set; }
}
```

## Remarks

TBD.

# Config Settings ([BLEServer](#bleserver-component) Component)

 The component 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 component, access to these *internal properties* is provided through the [Config](#config-method-bleserver-component) 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-component) 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 component 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 component 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 component 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 component 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 component 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*.

**UseInternalSecurityAPI**: Whether or not to use the system security libraries or an internal implementation. When set to *false*, the component will use the system security libraries by default to perform cryptographic functions where applicable. In this case, calls to unmanaged code will be made. In certain environments, this is not desirable. To use a completely managed security implementation, set this setting to *true*.

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

 On Windows, this setting is set to *false* by default. On Linux/macOS, this setting is set to *true* by default.

NOTE: This setting is static. The value set is applicable to all components used in the application.

When this value is set, the product's system dynamic link library (DLL) is no longer required as a reference, as all unmanaged code is stored in that file.

# Trappable Errors ([BLEServer](#bleserver-component) Component)

### 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 | Component 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). |