DLNAMediaServer.h

Go to the documentation of this file.

// Minimal header-only Digital Media Server (MediaServer) device
#pragma once
 
#include "DLNAMediaServerDescr.h"
#include "MediaItem.h"
#include "basic/EscapingPrint.h"
#include "basic/Printf.h"
#include "basic/Str.h"
#include "dlna/common/Action.h"
#include "dlna/devices/DLNADevice.h"
#include "dlna/devices/MediaServer/MediaItem.h"
#include "dlna/udp/IUDPService.h"
#include "dlna/xml/XMLParserPrint.h"
#include "dlna/xml/XMLPrinter.h"
#include "http/Http.h"
#include "http/Server/IHttpServer.h"
 
namespace tiny_dlna {
 
template <typename ClientType>
class DLNAMediaServer : public DLNADeviceInfo {
 public:
  using HttpClient = ClientType;
  using DeviceType = DLNADevice<ClientType>;
  typedef void (*PrepareDataCallback)(
      const char* objectID, ContentQueryType queryType, const char* filter,
      int startingIndex, int requestedCount, const char* sortCriteria,
      int& numberReturned, int& totalMatches, int& updateID, void* reference);
 
  typedef bool (*GetDataCallback)(int index, MediaItem& item, void* reference);
  typedef size_t (*GetDataCallbackPrint)(int index, Print& out,
                                         void* reference);
 
  DLNAMediaServer() {
    setUDN(usn);
    setSerialNumber("1.0");
    setDeviceType(st);
    setFriendlyName("ArduinoMediaServer");
    setManufacturer("TinyDLNA");
    setManufacturerURL("https://github.com/pschatzmann/arduino-dlna");
    setModelName("TinyDLNA MediaServer");
    setModelNumber("1.0");
    setBaseURL("http://localhost:44757");
    setupRules();
  }
  DLNAMediaServer(IHttpServer& server, IUDPService& udp) : DLNAMediaServer() {
    // use setters so derived classes or overrides get a consistent path
    setHttpServer(server);
    setUdpService(udp);
    dlna_device.setReference(this);
  }
 
  ~DLNAMediaServer() { end(); }
 
  void setHttpServer(IHttpServer& server) {
    p_server = &server;
    setupServicesImpl(&server);
  }
 
  void setUdpService(IUDPService& udp) { p_udp_member = &udp; }
 
  bool begin() {
    DlnaLogger.log(DlnaLogLevel::Info, "MediaServer::begin");
    return dlna_device.begin(*this, *p_udp_member, *p_server);
  }
 
  void end() {
    DlnaLogger.log(DlnaLogLevel::Info, "MediaServer::end");
    dlna_device.end();
  }
 
  bool loop(int loopAction = RUN_ALL) { return dlna_device.loop(loopAction); }
 
  void setSearchCapabilities(const char* caps) { g_search_capabiities = caps; }
 
  const char* getSearchCapabilities() { return g_search_capabiities; }
 
  void setSortCapabilities(const char* caps) { g_sort_capabilities = caps; }
 
  const char* getSortCapabilities() { return g_sort_capabilities; }
 
  void setConnectionID(const char* id) { connectionID = id; }
 
  const char* getConnectionID() { return connectionID; }
 
  void setProtocols(const char* source, const char* sink = "") {
    sourceProto = source;
    sinkProto = sink;
    // publish protocol info change to ConnectionManager subscribers
    // Build writer that will use live state from the device at publish time
    auto writer = [](Print& out, void* ref) -> size_t {
      auto self = (DLNAMediaServer*)ref;
      size_t result = 0;
      result += out.print("<SourceProtocolInfo val=\"");
      result += out.print(StrView(self->getSourceProtocols()).c_str());
      result += out.println("\"/>");
      result += out.print("<SinkProtocolInfo val=\"");
      result += out.print(StrView(self->getSinkProtocols()).c_str());
      result += out.println("\"/>");
      return result;
    };
    addChange("CMS", writer);
  }
 
  const char* getSourceProtocols() { return sourceProto; }
 
  const char* getSinkProtocols() { return sinkProto; }
 
  void setPrepareDataCallback(PrepareDataCallback cb) { prepare_data_cb = cb; }
 
  void setGetDataCallback(GetDataCallback cb) { get_data_cb = cb; }
  void setGetDataCallback(GetDataCallbackPrint cb) { get_data_print_cb = cb; }
 
  void setReference(void* ref) { reference_ = ref; }
 
  IHttpServer* getHttpServer() { return p_server; }
 
  int getSystemUpdateID() { return g_stream_updateID; }
 
  int incrementSystemUpdateID() { return ++g_stream_updateID; }
 
  IDevice& device() { return dlna_device; }
 
  void setSubscriptionsActive(bool flag) {
    dlna_device.setSubscriptionsActive(flag);
  }
 
  bool isSubscriptionsActive() { return dlna_device.isSubscriptionsActive(); }
 
  void setCustomActionRule(const char* suffix,
                           bool (*handler)(IClientHandler*, DLNAMediaServer*, ActionRequest&, IHttpServer&)) {
    for (size_t i = 0; i < rules.size(); ++i) {
      if (StrView(rules[i].suffix).equals(suffix)) {
        rules[i].handler = handler;
        return;
      }
    }
    rules.push_back({suffix, handler});
  }
 
  void setContentDirectoryDescr(DLNADescr& d) { p_contentDirectoryDescr = &d; }
 
  DLNADescr& getContentDirectoryDescr() { return *p_contentDirectoryDescr; }
 
  void setConnectionMgrDescr(DLNADescr& d) { p_connmgrDescr = &d; }
 
  DLNADescr& getConnectionMgrDescr() { return *p_connmgrDescr; }
 
  void logStatus() { return dlna_device.logStatus(); }
 
 protected:
  struct ActionRule {
    const char* suffix;
    bool (*handler)(IClientHandler&, DLNAMediaServer*, ActionRequest&, IHttpServer&);
  };
 
  DeviceType dlna_device;
  PrepareDataCallback prepare_data_cb = nullptr;
  GetDataCallback get_data_cb = nullptr;
  GetDataCallbackPrint get_data_print_cb = nullptr;
  IHttpServer* p_server = nullptr;
  IUDPService* p_udp_member = nullptr;
  void* reference_ = nullptr;
  GetDataCallback g_stream_get_data_cb = nullptr;
  int g_stream_numberReturned = 0;
  int g_stream_totalMatches = 0;
  int g_stream_updateID = 1;
  int g_stream_startingIndex = 0;
  void* g_stream_reference = nullptr;
  const char* st = "urn:schemas-upnp-org:device:MediaServer:1";
  const char* usn = "uuid:media-server-0000-0000-0000-000000000001";
  const char* g_search_capabiities =
      "dc:title,dc:creator,upnp:class,upnp:genre,"
      "upnp:album,upnp:artist,upnp:albumArtURI";
  const char* g_sort_capabilities =
      "dc:title,dc:date,upnp:class,upnp:album,upnp:episodeNumber,upnp:"
      "originalTrackNumber";
  // Default protocol info values (use DLNA_PROTOCOL by default)
  const char* sourceProto = DLNA_PROTOCOL_AUDIO;
  const char* sinkProto = "";
  const char* connectionID = "0";
  Vector<ActionRule> rules;
  // Per-instance descriptor objects (default-initialized). These allow callers
  // to customize the SCPD delivered for this MediaServer instance.
  DLNAMediaServerContentDirectoryDescr default_contentDirectoryDescr;
  DLNADescr* p_contentDirectoryDescr = &default_contentDirectoryDescr;
  DLNAMediaServerConnectionMgrDescr default_connectionMgrDescr;
  DLNADescr* p_connmgrDescr = &default_connectionMgrDescr;
 
  void addChange(const char* serviceAbbrev,
                 std::function<size_t(Print&, void*)> changeWriter) {
    dlna_device.addChange(serviceAbbrev, changeWriter, this);
  }
 
  void publishAVT() {
    DlnaLogger.log(DlnaLogLevel::Info, "MediaServer::publishAVT");
    // Publish SystemUpdateID using a writer that reads the current value
    auto writer = [](Print& out, void* ref) -> size_t {
      auto self = (DLNAMediaServer*)ref;
      size_t result = 0;
      result += out.print("<SystemUpdateID val=\"");
      result += out.print(self->g_stream_updateID);
      result += out.println("\"/>");
      return result;
    };
    addChange("AVT", writer);
  }
 
  void publishCMS() {
    DlnaLogger.log(DlnaLogLevel::Info, "MediaServer::publishCMS");
    // Publish current ConnectionManager properties using a writer that
    // reads live state from the device
    auto writer = [](Print& out, void* ref) -> size_t {
      auto self = (DLNAMediaServer*)ref;
      size_t result = 0;
      result += out.print("<SourceProtocolInfo val=\"");
      result += out.print(StrView(self->getSourceProtocols()).c_str());
      result += out.println("\"/>");
      result += out.print("<SinkProtocolInfo val=\"");
      result += out.print(StrView(self->getSinkProtocols()).c_str());
      result += out.println("\"/>");
      result += out.print("<CurrentConnectionIDs val=\"");
      result += out.print(StrView(self->connectionID).c_str());
      result += out.println("\"/>");
      return result;
    };
    addChange("CMS", writer);
  }
 
  void setupServicesImpl(IHttpServer* server) {
    DlnaLogger.log(DlnaLogLevel::Info, "MediaServer::setupServices");
 
    // register the individual services via helpers
    setupContentDirectoryService(server);
    setupConnectionManagerService(server);
  }
 
  static void contentDescCB(IClientHandler& client, IHttpServer* server, const char* requestPath,
                            HttpRequestHandlerLine* hl) {
    DLNAMediaServer* self = getMediaServer(server);
    assert(self != nullptr);
    // Non-capturing lambda matches function-pointer signature and can be
    // passed directly to reply (avoids extra static helpers).
    client.reply(
      "text/xml",
      [](Print& out, void* ref) -> size_t {
          size_t result = 0;
          if (ref) {
            auto self = (DLNAMediaServer*)ref;
            result += self->getContentDirectoryDescr().printDescr(out);
          } else {
            tiny_dlna::DLNAMediaServerContentDirectoryDescr descr;
            result += descr.printDescr(out);
          }
          return result;
        },
        200, nullptr, self);
  }
 
  static void connDescCB(IClientHandler& client, IHttpServer* server, const char* requestPath,
                         HttpRequestHandlerLine* hl) {
    DLNAMediaServer* self = getMediaServer(server);
 
    client.reply(
      "text/xml",
      [](Print& out, void* ref) -> size_t {
          size_t result = 0;
          if (ref) {
            auto self = (DLNAMediaServer*)ref;
            result += self->getConnectionMgrDescr().printDescr(out);
          } else {
            tiny_dlna::DLNAMediaServerConnectionMgrDescr descr;
            result += descr.printDescr(out);
          }
          return result;
        },
        200, nullptr, self);
  }
 
  // (Removed static helper functions — lambdas are used inline at callsite.)
 
  static void eventSubscriptionHandler(IClientHandler& client, IHttpServer* server,
                                       const char* requestPath,
                                       HttpRequestHandlerLine* hl) {
    bool is_subscribe = false;
    DeviceType::handleSubscription(server, &client, requestPath, hl, is_subscribe);
    if (is_subscribe) {
      DLNAMediaServer* self = getMediaServer(server);
      assert(self != nullptr);
      StrView request_path_str(requestPath);
      if (request_path_str.contains("/CD/"))
        self->publishAVT();
      else if (request_path_str.contains("/CM/"))
        self->publishCMS();
      else
        DlnaLogger.log(DlnaLogLevel::Warning,
                       "eventSubscriptionHandler: Unknown request path: %s",
                       requestPath);
    }
  }
 
  void setupContentDirectoryService(IHttpServer* server) {
    DLNAServiceInfo cd;
     cd.setup("urn:schemas-upnp-org:service:ContentDirectory:1",
           "urn:upnp-org:serviceId:ContentDirectory", "/CD/service.xml",
           &DLNAMediaServer::contentDescCB, "/CD/control",
           &DLNAMediaServer::contentDirectoryControlCB, "/CD/event",
           [](IClientHandler& client, IHttpServer*, const char*, HttpRequestHandlerLine*) { client.replyOK(); });
 
    // subscription namespace abbreviation used for event publishing
    cd.subscription_namespace_abbrev = "AVT";
 
    addService(cd);
  }
 
  void setupConnectionManagerService(IHttpServer* server) {
    DLNAServiceInfo cm;
    cm.setup("urn:schemas-upnp-org:service:ConnectionManager:1",
         "urn:upnp-org:serviceId:ConnectionManager", "/CM/service.xml",
         &DLNAMediaServer::connDescCB, "/CM/control",
         (http_callback)&DLNAMediaServer::connmgrControlCB, "/CM/event",
         (http_callback)&DLNAMediaServer::eventSubscriptionHandler);
 
    // subscription namespace abbreviation used for event publishing
    cm.subscription_namespace_abbrev = "CMS";
 
    addService(cm);
  }
 
  bool processAction(ActionRequest& action, IHttpServer& server, IClientHandler& client) {
    DlnaLogger.log(DlnaLogLevel::Info, "DLNAMediaServer::processAction: %s",
                   action.getAction());
    auto& action_str = action.getActionStr();
    if (action_str.isEmpty()) {
      DlnaLogger.log(DlnaLogLevel::Error, "Empty action received");
      client.replyNotFound();
      return false;
    }
    for (const auto& rule : rules) {
      if (action_str.endsWith(rule.suffix)) {
        return rule.handler(client, this, action, server);
      }
    }
        DlnaLogger.log(DlnaLogLevel::Error, "Unsupported action: %s",
          action.getAction());
        client.replyNotFound();
        return false;
  }
 
  bool processActionBrowse(ActionRequest& action, IHttpServer& server, IClientHandler& client) {
    DlnaLogger.log(DlnaLogLevel::Info, "processActionBrowse");
    int numberReturned = 0;
    int totalMatches = 0;
    int updateID = g_stream_updateID;
 
    // extract paging args
    int startingIndex = action.getArgumentIntValue("StartingIndex");
    int requestedCount = action.getArgumentIntValue("RequestedCount");
 
    // determine query type (BrowseDirectChildren / BrowseMetadata / Search)
    ContentQueryType qtype =
        parseContentQueryType(action.getArgumentValue("BrowseFlag"));
    // query for data
    if (prepare_data_cb) {
      prepare_data_cb(action.getArgumentValue("ObjectID"), qtype,
                      action.getArgumentValue("Filter"), startingIndex,
                      requestedCount, action.getArgumentValue("SortCriteria"),
                      numberReturned, totalMatches, updateID, reference_);
    }
 
    // Store streaming state and reply using callback writer
    g_stream_numberReturned = numberReturned;
    g_stream_totalMatches = totalMatches;
    g_stream_updateID = updateID;
    g_stream_startingIndex = startingIndex;
 
    client.reply(
        "text/xml",
        [](Print& out, void* ref) -> size_t {
          auto self = (DLNAMediaServer*)ref;
          return self->streamActionItems(out, "BrowseResponse",
                                         self->g_stream_startingIndex);
        },
        200, nullptr, this);
    return true;
  }
 
  bool processActionSearch(ActionRequest& action, IHttpServer& server, IClientHandler& client) {
    DlnaLogger.log(DlnaLogLevel::Info, "processActionSearch");
    int numberReturned = 0;
    int totalMatches = 0;
    int updateID = g_stream_updateID;
 
    // extract paging args
    int startingIndex = action.getArgumentIntValue("StartingIndex");
    int requestedCount = action.getArgumentIntValue("RequestedCount");
 
    // For Search actions we always use the Search query type regardless of
    // any provided BrowseFlag; this ensures Search semantics are preserved.
    ContentQueryType qtype = ContentQueryType::Search;
    // query for data
    if (prepare_data_cb) {
      prepare_data_cb(action.getArgumentValue("ContainerID"), qtype,
                      action.getArgumentValue("Filter"), startingIndex,
                      requestedCount, action.getArgumentValue("SortCriteria"),
                      numberReturned, totalMatches, updateID, reference_);
    }
 
    // Store streaming state and reply using callback writer
    g_stream_numberReturned = numberReturned;
    g_stream_totalMatches = totalMatches;
    g_stream_updateID = updateID;
    g_stream_startingIndex = startingIndex;
 
    client.reply(
        "text/xml",
        [](Print& out, void* ref) -> size_t {
          auto self = (DLNAMediaServer*)ref;
          return self->streamActionItems(out, "SearchResponse",
                                         self->g_stream_startingIndex);
        },
        200, nullptr, this);
    return true;
  }
 
  bool processActionGetSearchCapabilities(ActionRequest& action,
                                          IHttpServer& server, IClientHandler& client) {
    client.reply(
        "text/xml",
        [](Print& out, void* ref) -> size_t {
          auto self = (DLNAMediaServer*)ref;
          size_t written = 0;
          written += self->soapEnvelopeStart(out);
          written += self->actionResponseStart(
            out, "GetSearchCapabilitiesResponse",
            "urn:schemas-upnp-org:service:ContentDirectory:1");
          written += out.print("<SearchCaps>");
          written += out.print(StrView(self->g_search_capabiities).c_str());
          written += out.print("</SearchCaps>\r\n");
          written +=
            self->actionResponseEnd(out, "GetSearchCapabilitiesResponse");
          written += self->soapEnvelopeEnd(out);
          return written;
        },
        200, nullptr, this);
    DlnaLogger.log(DlnaLogLevel::Info,
                   "processActionGetSearchCapabilities (callback)");
    return true;
  }
 
  bool processActionGetSortCapabilities(ActionRequest& action,
                                        IHttpServer& server, IClientHandler& client) {
    client.reply(
        "text/xml",
        [](Print& out, void* ref) -> size_t {
          auto self = (DLNAMediaServer*)ref;
          size_t written = 0;
          written += self->soapEnvelopeStart(out);
          written += self->actionResponseStart(
            out, "GetSortCapabilitiesResponse",
            "urn:schemas-upnp-org:service:ContentDirectory:1");
          written += out.print("<SortCaps>");
          written += out.print(StrView(self->g_sort_capabilities).c_str());
          written += out.print("</SortCaps>\r\n");
          written +=
            self->actionResponseEnd(out, "GetSortCapabilitiesResponse");
          written += self->soapEnvelopeEnd(out);
          return written;
        },
        200, nullptr, this);
    DlnaLogger.log(DlnaLogLevel::Info,
                   "processActionGetSortCapabilities (callback)");
    return true;
  }
 
  bool processActionGetSystemUpdateID(ActionRequest& action,
                                      IHttpServer& server, IClientHandler& client) {
    client.reply(
        "text/xml",
        [](Print& out, void* ref) -> size_t {
          auto self = (DLNAMediaServer*)ref;
          size_t written = 0;
          written += self->soapEnvelopeStart(out);
          written += self->actionResponseStart(
            out, "GetSystemUpdateIDResponse",
            "urn:schemas-upnp-org:service:ContentDirectory:1");
          Printf pr{out};
          written += static_cast<size_t>(
            pr.printf("<Id>%d</Id>\r\n", self->g_stream_updateID));
          written += self->actionResponseEnd(out, "GetSystemUpdateIDResponse");
          written += self->soapEnvelopeEnd(out);
          return written;
        },
        200, nullptr, this);
    DlnaLogger.log(DlnaLogLevel::Info,
                   "processActionGetSystemUpdateID (callback): %d",
                   g_stream_updateID);
    return true;
  }
 
  bool processActionGetProtocolInfo(ActionRequest& action,
                                    IHttpServer& server, IClientHandler& client) {
    // Stream reply directly using a writer callback to avoid temporary buffers
    client.reply(
        "text/xml",
        [](Print& out, void* ref) -> size_t {
          auto self = static_cast<DLNAMediaServer*>(ref);
          return DeviceType::replyGetProtocolInfo(out, self->sourceProto,
                                                 self->sinkProto);
        },
        200, nullptr, this);
    return true;
  }
 
  bool processActionGetCurrentConnectionIDs(ActionRequest& action,
                                            IHttpServer& server, IClientHandler& client) {
    // Stream reply directly using a writer callback
    client.reply(
        "text/xml",
        [](Print& out, void* ref) -> size_t {
          auto self = static_cast<DLNAMediaServer*>(ref);
          return DeviceType::replyGetCurrentConnectionIDs(out,
                                                         self->connectionID);
        },
        200, nullptr, this);
    return true;
  }
  bool processActionGetCurrentConnectionInfo(ActionRequest& action,
                                             IHttpServer& server, IClientHandler& client) {
    // Read requested ConnectionID (not used in this simple implementation)
    int connId = action.getArgumentIntValue("ConnectionID");
 
    // Stream the GetCurrentConnectionInfo response using chunked encoding
    // to avoid building the full response in memory and to remain
    // consistent with other handlers.
    client.reply(
        "text/xml",
        [](Print& out, void* ref) -> size_t {
          auto self = static_cast<DLNAMediaServer*>(ref);
          return DeviceType::replyGetCurrentConnectionInfo(
            out, self->sourceProto, self->connectionID, "Output");
        },
        200, nullptr, this);
    return true;
  }
 
  ContentQueryType parseContentQueryType(const char* flag) {
    StrView fv(flag);
    if (fv.equals("BrowseDirectChildren"))
      return ContentQueryType::BrowseChildren;
    if (fv.equals("BrowseMetadata")) return ContentQueryType::BrowseMetadata;
    // fallback
    return ContentQueryType::BrowseMetadata;
  }
 
  size_t soapEnvelopeStart(Print& out) {
    size_t written = 0;
    written += out.print("<?xml version=\"1.0\" encoding=\"utf-8\"?>\r\n");
    written += out.print(
        "<s:Envelope xmlns:s=\"http://schemas.xmlsoap.org/soap/envelope/\" ");
    written += out.print(
        "s:encodingStyle=\"http://schemas.xmlsoap.org/soap/encoding/\">\r\n");
    written += out.print("<s:Body>\r\n");
    return written;
  }
 
  size_t soapEnvelopeEnd(Print& out) {
    size_t written = 0;
    written += out.print("</s:Body>\r\n");
    written += out.print("</s:Envelope>\r\n");
    return written;
  }
 
  size_t actionResponseStart(Print& out, const char* responseName,
                             const char* serviceNS) {
    // writes: <u:ResponseName xmlns:u="serviceNS">
    Printf pr{out};
    return static_cast<size_t>(
        pr.printf("<u:%s xmlns:u=\"%s\">\r\n", responseName, serviceNS));
  }
 
  size_t actionResponseEnd(Print& out, const char* responseName) {
    Printf pr{out};
    return static_cast<size_t>(pr.printf("</u:%s>\r\n", responseName));
  }
 
  size_t streamActionItems(Print& out, const char* responseName,
                           int startingIndex) {
    // SOAP envelope start and response wrapper
    size_t written = 0;
    written += soapEnvelopeStart(out);
    written += actionResponseStart(
        out, responseName, "urn:schemas-upnp-org:service:ContentDirectory:1");
 
    // Result -> DIDL-Lite
    written += out.println("<Result>");
    // DIDL root with namespaces
    written += streamDIDL(out, g_stream_numberReturned, startingIndex);
    written += out.print("</Result>\r\n");
 
    // numeric fields
    Printf pr{out};
    written += static_cast<size_t>(pr.printf(
        "<NumberReturned>%d</NumberReturned>\r\n", g_stream_numberReturned));
    written += static_cast<size_t>(pr.printf(
        "<TotalMatches>%d</TotalMatches>\r\n", g_stream_totalMatches));
    written += static_cast<size_t>(
        pr.printf("<UpdateID>%d</UpdateID>\r\n", g_stream_updateID));
 
    written += actionResponseEnd(out, responseName);
    written += soapEnvelopeEnd(out);
    return written;
  }
 
  size_t streamDIDL(Print& out, int numberReturned, int startingIndex) {
    size_t written = 0;
    // Stream DIDL-Lite Result payload using helper
    written += out.print(
        "&lt;DIDL-Lite xmlns:dc=\"http://purl.org/dc/elements/1.1/\" "
        "xmlns:upnp=\"urn:schemas-upnp-org:metadata-1-0/upnp/\" "
        "xmlns=\"urn:schemas-upnp-org:metadata-1-0/DIDL-Lite/\"&gt;\r\n");
 
    written += streamDIDLItems(out, numberReturned, startingIndex);
 
    written += out.print("&lt;/DIDL-Lite&gt;\r\n");
    return written;
  }
 
  // Streams each MediaItem entry (container/item with title,
  // class and optional resource). Returns bytes written.
  // Single-pass loop that prefers get_data_print_cb and falls back
  // to get_data_cb for any item where print produced 0 bytes.
  size_t streamDIDLItems(Print& out, int numberReturned, int startingIndex) {
    if (get_data_print_cb == nullptr && get_data_cb == nullptr) {
      // no data callback defined
      return 0;
    }
    EscapingPrint esc_out(out);
    size_t total = 0;
    for (int i = 0; i < numberReturned; ++i) {
      int idx = startingIndex + i;
 
      // 1) Try print callback if present
      if (get_data_print_cb) {
        size_t w = get_data_print_cb(idx, esc_out, reference_);
        if (w > 0) {
          total += w;
          continue;  // done with this item
        }
      }
 
      // 2) Structured callback path
      if (get_data_cb) {
        MediaItem item;
        if (!get_data_cb(idx, item, reference_)) break;  // end-of-list
        total += streamDIDLItem(esc_out, item);
        continue;
      }
    }
    return total;
  }
 
  // Print a single MediaItem as escaped DIDL (returns bytes written)
  size_t streamDIDLItem(Print& out, const MediaItem& item) {
    size_t written = 0;
    const char* mediaItemClassStr = toStr(item.itemClass);
    const char* nodeName =
        (item.itemClass == MediaItemClass::Folder) ? "container" : "item";
    Printf pr{out};
    written += static_cast<size_t>(
        pr.printf("<%s id=\"%s\" parentID=\"%s\" restricted=\"%d\">", nodeName,
                  item.id ? item.id : "", item.parentID ? item.parentID : "0",
                  item.restricted ? 1 : 0));
 
    written += out.print("<dc:title>");
    written += out.print(StrView(item.title).c_str());
    written += out.print("</dc:title>\r\n");
    if (mediaItemClassStr != nullptr) {
      written += static_cast<size_t>(
          pr.printf("<upnp:class>%s</upnp:class>\r\n", mediaItemClassStr));
    }
 
    // Optional album art URI
    if (!StrView(item.albumArtURI).isEmpty()) {
      Str url_str = getUri(item.albumArtURI);
      written += out.print("<upnp:albumArtURI>");
      written += out.print(url_str.c_str());
      written += out.print("</upnp:albumArtURI>\r\n");
    }
 
    // res with optional protocolInfo attribute
    if (!StrView(item.resourceURI).isEmpty()) {
      if (!StrView(item.mimeType).isEmpty()) {
        written += static_cast<size_t>(
            pr.printf("<res protocolInfo=\"http-get:*:%s:*\">", item.mimeType));
      } else {
        written += out.print("<res>");
      }
      Str url_str = getUri(item.resourceURI);
      written += out.print(url_str.c_str());
      written += out.print("</res>\r\n");
    }
 
    written += static_cast<size_t>(pr.printf("</%s>\r\n", nodeName));
    return written;
  }
 
  Str getUri(const char* path) {
    Str url{256};
    // We got a valid url
    url = path;
    if (url.startsWith("http://")) {
      return url;
    }
    // We need to add the path to the base url
    url = getBaseURL();
    if (!StrView(path).startsWith("/")) {
      url += "/";
    }
    url += path;
    return url;
  }
 
  const char* toStr(MediaItemClass itemClass) {
    switch (itemClass) {
      case MediaItemClass::Music:
        return "object.item.audioItem.musicTrack";
      case MediaItemClass::Radio:
        return "object.item.audioItem.audioBroadcast";
      case MediaItemClass::Video:
        return "object.item.videoItem.movie";
      case MediaItemClass::Photo:
        return "object.item.imageItem.photo";
      case MediaItemClass::Folder:
        return "object.container";
      default:
        return nullptr;
    }
  }
 
  static void contentDirectoryControlCB(IClientHandler& client, IHttpServer* server,
                                        const char* requestPath,
                                        HttpRequestHandlerLine* hl) {
    ActionRequest action;
    DeviceType::parseActionRequest(server, client, requestPath, hl, action);
 
    // If a user-provided callback is registered, hand over the parsed
    // ActionRequest for custom handling. The callback is responsible for
    // writing the HTTP reply if it handles the action.
    DLNAMediaServer* ms = getMediaServer(server);
 
    // process the requested action using instance method if available
    if (ms) {
      if (ms->processAction(action, *server, client)) return;
    }
    client.replyNotFound();
  }
 
  static DLNAMediaServer* getMediaServer(IHttpServer* server) {
    if (!server) return nullptr;
    auto* dev = static_cast<IDevice*>(server->getReference());
    if (!dev) return nullptr;
    return static_cast<DLNAMediaServer*>(dev->getReference());
  }
 
  static void connmgrControlCB(IClientHandler& client, IHttpServer* server, const char* requestPath,
                               HttpRequestHandlerLine* hl) {
    ActionRequest action;
    DeviceType::parseActionRequest(server, client, requestPath, hl, action);
 
    DLNAMediaServer* ms = getMediaServer(server);
    if (!ms) {
      client.replyNotFound();
      return;
    }
    // Use rules-based dispatch for ConnectionManager actions
    if (ms->processAction(action, *server, client)) return;
    client.replyNotFound();
  }
 
  void setupRules() {
    // ContentDirectory rules
    rules.push_back({"Browse", [](IClientHandler& client, DLNAMediaServer* self, ActionRequest& action,
                                  IHttpServer& server) {
                       return self->processActionBrowse(action, server, client);
                     }});
    rules.push_back({"Search", [](IClientHandler& client, DLNAMediaServer* self, ActionRequest& action,
                                  IHttpServer& server) {
                       return self->processActionSearch(action, server, client);
                     }});
    rules.push_back(
        {"GetSearchCapabilities",
         [](IClientHandler& client, DLNAMediaServer* self, ActionRequest& action, IHttpServer& server) {
           return self->processActionGetSearchCapabilities(action, server, client);
         }});
    rules.push_back(
        {"GetSortCapabilities",
         [](IClientHandler& client, DLNAMediaServer* self, ActionRequest& action, IHttpServer& server) {
           return self->processActionGetSortCapabilities(action, server, client);
         }});
    rules.push_back(
        {"GetSystemUpdateID",
         [](IClientHandler& client, DLNAMediaServer* self, ActionRequest& action, IHttpServer& server) {
           return self->processActionGetSystemUpdateID(action, server, client);
         }});
    // ConnectionManager rules
    rules.push_back(
        {"GetProtocolInfo",
         [](IClientHandler& client, DLNAMediaServer* self, ActionRequest& action, IHttpServer& server) {
           return self->processActionGetProtocolInfo(action, server, client);
         }});
    rules.push_back(
        {"GetCurrentConnectionIDs",
         [](IClientHandler& client, DLNAMediaServer* self, ActionRequest& action, IHttpServer& server) {
           return self->processActionGetCurrentConnectionIDs(action, server, client);
         }});
    rules.push_back(
        {"GetCurrentConnectionInfo",
         [](IClientHandler& client, DLNAMediaServer* self, ActionRequest& action, IHttpServer& server) {
           return self->processActionGetCurrentConnectionInfo(action, server, client);
         }});
  }
};
 
}  // namespace tiny_dlna