#lang at-exp racket/base
;; For legal info, see file "info.rkt".

(require (planet neil/mcfly)
         )

(doc (section "Introduction")

     @para{
         This is a Racket library for discovering, accessing and invoking
         UPnP services.
         
         }
     
     @margin-note{
         This UPnP library currently only implements the client side, that
         is the service consumer.
         
         }
     
     )

(doc (section "How it works")
     @para{
         First you must initiate a search with @racket[upnp-discovery] which will begin
         to collect service advertisements via UDP, when you are ready you can
         search for a UPnP service by service ID or type. Finally you create a
         "service wrapper" from a UPnP service.
         
         }
           
     (RACKETBLOCK0
      (define d (upnp-discovery))
      (define s (upnp-search-service-srvid d "urn:upnp-org:serviceId:WANIPConn1"))
      (define c (upnp-make-service-wrapper s))
      )
           
     @para{
         With the service wrapper, you can create functions that wrap SOAP
         request calls to the UPnP service:
         }

     (RACKETBLOCK0
      (define get-external-ip
        (c "GetExternalIPAddress" '("NewExternalIPAddress")))
      
      (define add-port-mapping
        (c "AddPortMapping" '()
           "NewRemoteHost" "NewExternalPort" "NewProtocol"
           "NewInternalPort" "NewInternalClient" "NewEnabled"
           "NewPortMappingDescription" "NewLeaseDuration"))
      )
  
     @para{
         And then use @racket[(get-external-ip)] to get the external ip, or use
         @racket[(add-port-mapping ...)] with the parameters.
         }
           
     )

(doc (section "Known Issues")

     @para{
         At this moment, this library seems to work fine to grab an IP address on my
         personal router :). This library is relatively new, so certain things might 
         not work quite right or might not work at all with different brands of
         routers, other networking equipment and anything else that might provide UPnP
         services.
         
         })

(doc history

     (#:planet 1:0 #:date "2012-11-16"
               "Initial release."))