Skip to content
Shiny.NET

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)
);
// IBleHubHost
host.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.
  • Authorize sees the request (file name, size, upload or download) and the hub client it came from, when it can be matched.

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>();
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.
  • CanTransferFiles is false when the host doesn’t serve files or L2CAP isn’t available. The file methods then throw BleHubFileTransferNotSupportedException.
  • Refusals (not found, not permitted, too large…) throw L2CapTransferException with an Error code.
  • Failed downloads never leave a partial file behind.
Platform L2CAP
iOS / macOS / Mac Catalyst Yes
Android API 29+
Windows No

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 client
callHub.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 open
if (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.
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.
  • CanOpenMediaChannel is false when the host didn’t enable media channels, the host is older than 1.4, or L2CAP isn’t available. OpenMediaChannel then throws NotSupportedException. A refused channel throws BleHubException.
  • The channel closes when the hub connection ends. While still connected, call OpenMediaChannel again to reopen it.

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.