#lang scribble/manual

@(require (for-label racket/base
                     racket/contract
                     (file "../main.rkt")
                     (file "../services/content-directory.rkt")))

@title{ContentDirectory}

@defmodule[@racketmodname[racket-upnp/services/content-directory] #:module-paths ((file "../services/content-directory.rkt"))]

ContentDirectory is the low-level media-server service. Its browse and search
operations return raw DIDL-Lite XML. Applications that want parsed containers,
items, and resource URIs can use @racketmodname[racket-upnp/media-server].

@defproc[(content-directory? [value any/c]) boolean?]{Recognises a ContentDirectory service.}
@defproc[(device-content-directory [device upnp-device?]) (or/c #f upnp-service?)]{Returns the device's ContentDirectory service.}
@defproc[(content-directory-browse [directory content-directory?]
                                   [object-id string?]
                                   [#:metadata? metadata? boolean? #f]
                                   [#:filter filter string? "*"]
                                   [#:start start exact-nonnegative-integer? 0]
                                   [#:count count exact-nonnegative-integer? 0]
                                   [#:sort sort string? ""])
         content-result?]{Browses metadata or direct children and returns raw DIDL-Lite plus paging information.}
@defproc[(content-directory-search [directory content-directory?]
                                   [container-id string?]
                                   [search-criteria string?]
                                   [#:filter filter string? "*"]
                                   [#:start start exact-nonnegative-integer? 0]
                                   [#:count count exact-nonnegative-integer? 0]
                                   [#:sort sort string? ""])
         content-result?]{Searches a media server and returns raw DIDL-Lite plus paging information.}

@section{Result values}

@defproc[(content-result? [value any/c]) boolean?]{Recognises a ContentDirectory result.}
@defproc[(content-result-content [result content-result?]) string?]{Returns the raw DIDL-Lite XML.}
@defproc[(content-result-number-returned [result content-result?]) (or/c #f exact-nonnegative-integer?)]{Returns the number of entries in this page.}
@defproc[(content-result-total-matches [result content-result?]) (or/c #f exact-nonnegative-integer?)]{Returns the total number of matching entries.}
@defproc[(content-result-update-id [result content-result?]) (or/c #f exact-nonnegative-integer?)]{Returns the ContentDirectory update identifier.}