yuppie

README

yuppie is a library that supports building UPnP servers in Go

Installation

Run go get -u gitlab.com/mipimipi/yuppie.

Usage

You can focus on the specific application logic of your server and don't have to bother with all the generic UPnP stuff. yuppie takes care of ...

• Device discovery, i.e. SSDP notifications and search responses
• Provisioning of device and service descriptions
• Management of state variables
• Eventing
• Receipt and verification of service control calls, sending of responses

The yuppie server requires ...

• a device description
• service descriptions
• handler functions for HTTP and SOAP action calls

This example shows how a simple UPnP music server can be built with yuppie. You find more detailed information about how to use yuppie to build a server here.

Description files

The yuppie server requires a device and service descriptions. These descriptions can come from XML files (see [2], [3] and [4] for further information; see the example server for an example device description and an example description for a ContentDirectory service). yuppie provides functions to create the input data for the server from such files.

Configuration

Besides device and service descriptions, yuppie requires a simple configuration to create a server. If no configuration is provided the default values are used:

• All network interfaces are used by the server
• The server listens on port 8008

Logging

yuppie uses logrus for logging. It uses the logrus default configuration (i.e. output on stdout with text formatter and info level). If you don't want that, configure the output, formatter and level in your server application. This will also be adhered to by the logging of yuppie server.

Scope and Limitations

yuppie implements the UPnP Device Architecture version 2.0, except:

• SSDP update notifications

  yuppie does not send update notifications if network interfaces or server IP addresses changed. Thus, it's recommended to give the server a static IP address and to restart the server if network interfaces were changed.

• Chunked transfer encoding that was introduced with HTTP 1.1

• Custom UPnP data types

  yuppie only supports the standard UPnP data types

• Event subscriptions for specific state variables

  yuppie only supports event subscriptions for all evented state variables

Further Reading

[1] UPnP Standards and Architecture

[2] UPnP Device Architecture version 2.0 (PDF)

[3] UPnP ContentDirectory Service (PDF)

[4] UPnP ConnectionManager Service (PDF)

[5] UPnP MediaServer and MediaRenderer

Documentation

Index

• type Config
• type SOAPError
  • func (me SOAPError) IsNil() bool
• type SOAPRespArgs
• type Server
  • func New(cfg Config, rootDesc *desc.RootDevice, svcDescs desc.ServiceMap) (srv *Server, err error)
  • func (me *Server) BootID() uint32
  • func (me *Server) ConfigID() uint32
  • func (me *Server) Connect(ctx context.Context) (err error)
  • func (me *Server) Disconnect(ctx context.Context)
  • func (me *Server) Errors() <-chan error
  • func (me *Server) HTTPHandleFunc(pattern string, handleFunc func(http.ResponseWriter, *http.Request))
  • func (me *Server) PresentationHandleFunc(handleFunc func(http.ResponseWriter, *http.Request))
  • func (me *Server) Run(ctx context.Context, wg *sync.WaitGroup)
  • func (me *Server) SOAPHandleFunc(svcID string, act string, ...)
  • func (me *Server) ServerString() (s string)
  • func (me *Server) StateVariable(svcID, svName string) (StateVar, bool)
• type StateVar
• type UPnPErrorCode

Types

type Config

type Config struct {
	// Interfaces contain the names of the network interfaces to be used. If
	// Interfaces is empty, all available interfaces will be used
	Interfaces []string
	// Port is the port where the server listens
	Port int
	// MaxAge is the validity time period of the SSDP advertisement in seconds
	MaxAge int
	// ProductName is the product name used for the server string
	ProductName string
	// ProductVersion is the product version for the server string
	ProductVersion string
	// StatusFile is the path to the JSON file that persists data such as
	// state variables
	StatusFile string
	// IconRootDir is the root directory for device icons. I.e. if the icon url
	// in the device description is someDir/icon.png, for example, the icon
	// must be located in IconRootDir/someDir/icon.png
	IconRootDir string
}

Config represents the configuration of the UPnP server

type SOAPError

type SOAPError struct {
	Code UPnPErrorCode
	Desc string
}

SOAPError represents a SOAP error

func (SOAPError) IsNil

func (me SOAPError) IsNil() bool

IsNil returns true if the SOAP error is not really an error

type SOAPRespArgs

type SOAPRespArgs map[string]string

SOAPRespArgs maps argument name to argument value

type Server

type Server struct {
	Errs   chan error
	Device *rootDevice

	// Locals contains variables that are persisted in the status.json of
	// yuppie
	Locals map[string]string
	// contains filtered or unexported fields
}

Server represents the UPnP server

func New

func New(cfg Config, rootDesc *desc.RootDevice, svcDescs desc.ServiceMap) (srv *Server, err error)

New creates a new instance of the UPnP server from a device description and service descriptions. Note: The keys of the service map must correspond to the service ids in the device description

func (*Server) BootID

func (me *Server) BootID() uint32

BootID returns the current value of BOOTID.UPNP.ORG

func (*Server) ConfigID

func (me *Server) ConfigID() uint32

ConfigID returns the current value of CONFIGID.UPNP.ORG

func (*Server) Connect

func (me *Server) Connect(ctx context.Context) (err error)

Connect starts the SSDP processes and multicast eventing

func (*Server) Disconnect

func (me *Server) Disconnect(ctx context.Context)

Disconnect stops the SSDP processes and the multicast eventing

func (*Server) Errors

func (me *Server) Errors() <-chan error

Errors returns a receive-only channel for errors from the UPnP server

func (*Server) HTTPHandleFunc

func (me *Server) HTTPHandleFunc(pattern string, handleFunc func(http.ResponseWriter, *http.Request))

HTTPHandleFunc is a wrapper around http.ServeMux.HandleFunc. It allowes to register handler functions for HTTP requests for given patterns

func (*Server) PresentationHandleFunc

func (me *Server) PresentationHandleFunc(handleFunc func(http.ResponseWriter, *http.Request))

PresentationHandleFunc sets the handler function for HTTP calls to the presentation url of the root device

func (*Server) Run

func (me *Server) Run(ctx context.Context, wg *sync.WaitGroup)

Run starts the server. It can be stopped via the context ctx

func (*Server) SOAPHandleFunc

func (me *Server) SOAPHandleFunc(svcID string, act string, handler func(map[string]StateVar) (SOAPRespArgs, SOAPError))

SOAPHandleFunc allows to register functions to handle UPnP SOAP requests. Such handlers are defined per service ID / action combination

func (*Server) ServerString

func (me *Server) ServerString() (s string)

ServerString assembles the server string in the format "<OS>/<OS version> UPnP/<UPnP version> <product name>/<product version>"

func (*Server) StateVariable

func (me *Server) StateVariable(svcID, svName string) (StateVar, bool)

StateVariable returns the state variable svName of service svcID

type StateVar

type StateVar interface {
	Type() string
	Init(interface{}) error
	Get() interface{}
	Set(interface{}) error
	SetFromString(string) error
	IsNumeric() bool
	IsString() bool
	IsZero() bool
	String() string
	Lock()
	Unlock()
}

StateVar represents a SOAP variable (e.g. a SOAP state variable)

type UPnPErrorCode

type UPnPErrorCode uint

UPnPErrorCode represents an UPnP error code

const (
	// UPnPErrorInvalidAction is the code foran invalid action
	UPnPErrorInvalidAction UPnPErrorCode = 400
	// UPnPErrorInvalidArgs is the code for invalid arguments
	UPnPErrorInvalidArgs UPnPErrorCode = 402
	// UPnPErrorActionFailed is the code for a failed action
	UPnPErrorActionFailed UPnPErrorCode = 501
	// UPnPErrorArgValInvalid is the code for an invalid argument value
	UPnPErrorArgValInvalid UPnPErrorCode = 600
	// UPnPErrorArgValOutOfRange is the code for an argument value that is out
	// of range
	UPnPErrorArgValOutOfRange UPnPErrorCode = 601
	// UPnPErrorOptActionNotImplemented is the code for an action that is
	// called but not implemented
	UPnPErrorOptActionNotImplemented UPnPErrorCode = 602
	// UPnPErrorHumanRequired indicates that human interaction is required
	UPnPErrorHumanRequired UPnPErrorCode = 604
	// UPnPErrorStrTooLong indicates that a string is too long
	UPnPErrorStrTooLong UPnPErrorCode = 605
)