#lang scribble/manual

@(require
  (for-label
   racket/base
   (file "../media-server.rkt")))

@title{Media Servers}

@defmodule[(file "../media-server.rkt")]

This module provides a higher-level browser for UPnP and DLNA media servers.
It converts ContentDirectory DIDL-Lite XML into containers, items, and media
resources.

@defproc[(query-media-servers
          [#:interface interface (or/c #f string?) #f]
          [#:dns? dns? boolean? #f])
         (listof media-server?)]{

Discovers media servers.
}

@defproc[(get-media-server [filter-name string?])
         (or/c #f media-server?)]{

Returns the first discovered media server whose name contains
@racket[filter-name], ignoring case, or @racket[#f].
}

@defproc[(media-server? [value any/c]) boolean?]
@defproc[(media-server-name [server media-server?]) string?]
@defproc[(media-server-address [server media-server?]) string?]
@defproc[(media-server-manufacturer [server media-server?])
         (or/c #f string?)]
@defproc[(media-server-model [server media-server?])
         (or/c #f string?)]

@section{Browsing}

@defproc[(media-server-root
          [server media-server?]
          [#:start start exact-nonnegative-integer? 0]
          [#:count count exact-nonnegative-integer? 0])
         (listof media-entry?)]{

Browses object @tt{0}, the ContentDirectory root.
}

@defproc[(media-server-browse
          [server media-server?]
          [container (or/c string? media-container?) "0"]
          [#:start start exact-nonnegative-integer? 0]
          [#:count count exact-nonnegative-integer? 0])
         (listof media-entry?)]{

Browses one level below a container ID or a previously returned container.

In ContentDirectory, @racket[count] equal to zero asks the server to return all
remaining entries.  Use a positive count for large containers.
}

@defproc[(media-container-children
          [server media-server?]
          [container media-container?]
          [#:start start exact-nonnegative-integer? 0]
          [#:count count exact-nonnegative-integer? 0])
         (listof media-entry?)]{

Equivalent to browsing the supplied container.
}

@section{Entries}

@defproc[(media-entry? [value any/c]) boolean?]
@defproc[(media-entry-id [entry media-entry?]) (or/c #f string?)]
@defproc[(media-entry-parent-id [entry media-entry?]) (or/c #f string?)]
@defproc[(media-entry-title [entry media-entry?]) string?]
@defproc[(media-entry-class [entry media-entry?]) (or/c #f string?)]
@defproc[(media-entry-restricted? [entry media-entry?]) boolean?]

@defproc[(media-container? [value any/c]) boolean?]
@defproc[(media-container-child-count [container media-container?])
         (or/c #f exact-nonnegative-integer?)]
@defproc[(media-container-searchable? [container media-container?])
         boolean?]

@defproc[(media-item? [value any/c]) boolean?]
@defproc[(media-item-creator [item media-item?]) (or/c #f string?)]
@defproc[(media-item-artists [item media-item?]) (listof string?)]
@defproc[(media-item-album [item media-item?]) (or/c #f string?)]
@defproc[(media-item-genres [item media-item?]) (listof string?)]
@defproc[(media-item-date [item media-item?]) (or/c #f string?)]
@defproc[(media-item-album-art-uri [item media-item?])
         (or/c #f string?)]
@defproc[(media-item-resources [item media-item?])
         (listof media-resource?)]

@section{Resources}

@defproc[(media-resource? [value any/c]) boolean?]
@defproc[(media-resource-uri [resource media-resource?]) string?]
@defproc[(media-resource-protocol-info [resource media-resource?])
         (or/c #f string?)]
@defproc[(media-resource-content-type [resource media-resource?])
         (or/c #f string?)]
@defproc[(media-resource-size [resource media-resource?])
         (or/c #f exact-nonnegative-integer?)]
@defproc[(media-resource-duration [resource media-resource?])
         (or/c #f number?)]
@defproc[(media-resource-bitrate [resource media-resource?])
         (or/c #f exact-nonnegative-integer?)]
@defproc[(media-resource-sample-frequency [resource media-resource?])
         (or/c #f exact-nonnegative-integer?)]
@defproc[(media-resource-bits-per-sample [resource media-resource?])
         (or/c #f exact-nonnegative-integer?)]
@defproc[(media-resource-channels [resource media-resource?])
         (or/c #f exact-nonnegative-integer?)]
@defproc[(media-resource-resolution [resource media-resource?])
         (or/c #f string?)]