File Transfers
Hub messages are great for game moves, commands and state, but they are chunked over GATT at a few KB/s. Files, such as photos, logs and recordings, go over a separate L2CAP channel instead. It is much faster, and you get progress reporting.
builder.Services.AddBleHubServer(server => server .Host(o => o.EnableFileTransfers( Path.Combine(FileSystem.AppDataDirectory, "shared"), ft => { ft.AllowUploads = true; ft.AllowDownloads = true; ft.MaxUploadSize = 2 * 1024 * 1024; ft.OverwriteExistingUploads = false; ft.Authorize = req => req.Request.FileName.EndsWith(".jpg") && req.Client != null; } )) .AddHub<GameHub>(GameHubCharacteristicUuid));
// IBleHubHosthost.FileTransferred += (_, e) => Console.WriteLine($"{e.Client?.Name} {e.Type} {e.FileName} ({e.BytesTransferred} bytes)");host.FileTransferProgress += (_, e) => Console.WriteLine($"{e.FileName} {e.Progress.PercentComplete:P0}");- Safe paths: uploads land in the root directory and downloads are served from it. Peer-supplied names can never escape it.
Authorizesees the request (file name, size, upload or download) and the hub client it came from, when it can be matched.
Custom handling
Section titled “Custom handling”To serve from a database, generate content on the fly, or route per client, register an IBleHubFileHandler. Every
request must be accepted or rejected:
public class FileHandler : IBleHubFileHandler{ public async Task Handle(BleHubFileRequest request, CancellationToken ct) { var r = request.Request; if (r.Type == L2CapTransferType.Download && r.FileName == "scores.json") { var bytes = BuildScores(); await r.AcceptDownload(new MemoryStream(bytes), bytes.Length, cancellationToken: ct); } else { await r.Reject(L2CapTransferError.NotPermitted, "nope", ct); } }}
builder.Services.AddSingleton<IBleHubFileHandler, FileHandler>();Client
Section titled “Client”if (client.CanTransferFiles){ await client.UploadFile( localPhotoPath, "avatar-allan.jpg", new Progress<TransferProgress>(p => this.Progress = p.PercentComplete) );
await client.DownloadFile("scores.json", Path.Combine(FileSystem.CacheDirectory, "scores.json")); await client.UploadStream(stream, stream.Length, "log.txt");}- No setup: the client learns the L2CAP channel during the handshake, so there’s nothing to configure.
CanTransferFilesis false when the host doesn’t serve files or L2CAP isn’t available. The file methods then throwBleHubFileTransferNotSupportedException.- Refusals (not found, not permitted, too large…) throw
L2CapTransferExceptionwith anErrorcode. - Failed downloads never leave a partial file behind.
| Platform | L2CAP |
|---|---|
| iOS / macOS / Mac Catalyst | Yes |
| Android | API 29+ |
| Windows | No |
Media Channels
Section titled “Media Channels”A media channel is an ordered, two-way pipe of raw binary packets beside each hub connection, on an L2CAP channel of its own. Use it for live audio and video, or any steady stream of packets. Hub calls go through GATT at a few KB/s and through the serializer, so they suit neither. Available from 1.4.
builder.Services.AddBleHubServer(server => server .Host(o => o.EnableMediaChannels(maxPacketSize: 128 * 1024)) // opens a second L2CAP PSM on Start .AddHub<CallHub>(CallHubCharacteristicUuid));
// IHubContext<CallHub>: one channel per connected clientcallHub.MediaChannelOpened += (_, e) => _ = Task.Run(async () =>{ // e.Client is the hub client, e.Channel.ConnectionId is its connection id await foreach (var packet in e.Channel.Receive()) Play(e.Client, packet);});
IBleHubMediaChannel? channel = callHub.GetMediaChannel(connectionId); // null when that client has none openif (channel != null) await channel.Send(frame);- One PSM serves every hub.
EnableMediaChannels(maxPacketSize, secure)sets the largest packet either side may send (128 KB by default), and whether Android listens for secure channels. - A client has at most one channel. A new one replaces the old.
- The channel closes when the client disconnects or drops, when the hub stops, or when either side disposes it.
- When the device has no L2CAP, the hubs still start, and clients see
CanOpenMediaChannel == false.
Client
Section titled “Client”if (client.CanOpenMediaChannel){ var media = await client.OpenMediaChannel(ct); // returns the channel already open, if there is one _ = Task.Run(async () => { await foreach (var packet in media.Receive(ct)) Render(packet); }); await media.Send(encodedFrame, ct);}- No setup: the handshake gives the client the media PSM and a one-time token for its connection.
CanOpenMediaChannelis false when the host didn’t enable media channels, the host is older than 1.4, or L2CAP isn’t available.OpenMediaChannelthen throwsNotSupportedException. A refused channel throwsBleHubException.- The channel closes when the hub connection ends. While still connected, call
OpenMediaChannelagain to reopen it.
The channel
Section titled “The channel”IBleHubMediaChannel is the same on both sides:
| Member | |
|---|---|
Send(packet, ct) |
Serialized: packets arrive whole and in order, or the channel closes. A packet over MaxPacketSize throws ArgumentException. Sending on a closed channel throws BleHubException |
Receive(ct) |
The packets from the other side. One reader at a time. Completes when the channel closes. Packets that arrive before you read are buffered |
MaxPacketSize |
The host’s setting |
IsOpen / Completion |
Completion completes when the channel closes, for any reason |
ConnectionId |
The client’s connection id on the host, null on the client |
DisposeAsync() |
Closes the channel at both ends |
The packet format is yours: add sequence numbers and timestamps as your media needs. Over Wi-Fi, Universal Hubs carries the same channel, and builds audio and video calls on it.


