xmlrpc

package
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 3, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package xmlrpc implements just enough of the XML-RPC protocol to act as a HomeMatic CCU server. It is a tightened, server-side port of the gohomematic transport package.

All public surfaces are exported as Value types plus encode/decode helpers. Higher levels (the ccu package) translate Value trees into the loosely-typed map[string]any values that mirror the Python source.

Index

Constants

View Source 
const DefaultClientTimeout = 10 * time.Second

DefaultClientTimeout applies when the caller's context has no deadline.

View Source 
const DefaultRequestLimit = 10 * 1024 * 1024

DefaultRequestLimit bounds the body of an incoming XML-RPC request.

View Source 
const ISO8601CompactLayout = "20060102T15:04:05"

ISO8601CompactLayout is the CCU's canonical dateTime.iso8601 format.

Variables

This section is empty.

Functions

func AsBool 

func AsBool(v Value) (bool, bool)

AsBool extracts a Go bool from v.

func AsInt 

func AsInt(v Value) (int, bool)

AsInt extracts a Go int from v.

func AsString 

func AsString(v Value) (string, bool)

AsString extracts a Go string from v, accepting either StringValue or chardata that the decoder surfaced as such.

func EncodeCall 

func EncodeCall(w io.Writer, mc *MethodCall) error

EncodeCall writes mc to w using UTF-8 (sufficient for pydevccu clients; the original CCU emits ISO-8859-1 but accepts UTF-8 too).

func EncodeResponse 

func EncodeResponse(w io.Writer, mr *MethodResponse) error

EncodeResponse writes mr to w. If Fault is set, Params is ignored.

func IsTransport 

func IsTransport(err error) bool

IsTransport returns true when err looks like a recoverable network problem rather than a CCU-level fault.

func MarshalCallBytes 

func MarshalCallBytes(mc *MethodCall) ([]byte, error)

MarshalCallBytes is a convenience around EncodeCall.

func MarshalResponseBytes 

func MarshalResponseBytes(mr *MethodResponse) ([]byte, error)

MarshalResponseBytes is a convenience around EncodeResponse.

func Stringify 

func Stringify(v Value) string

Stringify renders a value in a compact debug form. The format is stable but unspecified; use only for logging.

func ToAny 

func ToAny(v Value) any

ToAny converts an XML-RPC value into its natural Go counterpart: struct→map[string]any, array→[]any, leaves to primitives.

Types

type ArrayValue 

type ArrayValue []Value

ArrayValue maps to <array><data>…</data></array>.

func AsArray 

func AsArray(v Value) (ArrayValue, bool)

AsArray extracts an array from v.

func (ArrayValue) Kind 

func (ArrayValue) Kind() Kind

func (ArrayValue) MarshalXML 

func (a ArrayValue) MarshalXML(e *xml.Encoder, _ xml.StartElement) error

type Base64Value 

type Base64Value []byte

Base64Value maps to <base64>.

func (Base64Value) Kind 

func (Base64Value) Kind() Kind

func (Base64Value) MarshalXML 

func (v Base64Value) MarshalXML(e *xml.Encoder, _ xml.StartElement) error

type BoolValue 

type BoolValue bool

BoolValue maps to <boolean>.

func (BoolValue) Kind 

func (BoolValue) Kind() Kind

func (BoolValue) MarshalXML 

func (v BoolValue) MarshalXML(e *xml.Encoder, _ xml.StartElement) error

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is a tiny XML-RPC client used by the simulator to push events back to registered callback endpoints (newDevices, deleteDevices, event, …). It is not exported through the public API.

func NewClient 

func NewClient(url string) *Client

NewClient returns a client targeting url.

func (*Client) Call 

func (c *Client) Call(ctx context.Context, method string, params []Value) (Value, error)

Call invokes method with params and returns the decoded value. A CCU fault is returned wrapped as *Fault.

func (*Client) URL 

func (c *Client) URL() string

URL returns the configured endpoint.

type DateTimeValue 

type DateTimeValue time.Time

DateTimeValue maps to <dateTime.iso8601>.

func (DateTimeValue) Kind 

func (DateTimeValue) Kind() Kind

func (DateTimeValue) MarshalXML 

func (v DateTimeValue) MarshalXML(e *xml.Encoder, _ xml.StartElement) error

func (DateTimeValue) Time 

func (v DateTimeValue) Time() time.Time

Time returns the wrapped Go time.

type DoubleValue 

type DoubleValue float64

DoubleValue maps to <double>.

func (DoubleValue) Kind 

func (DoubleValue) Kind() Kind

func (DoubleValue) MarshalXML 

func (v DoubleValue) MarshalXML(e *xml.Encoder, _ xml.StartElement) error

type Fault 

type Fault struct {
	Code    int
	Message string
}

Fault is the data carried by an XML-RPC <fault> response. It also implements error so handlers can return it directly.

func (*Fault) Error 

func (f *Fault) Error() string

type Handler 

type Handler struct {
	Mux    *Mux
	Logger *slog.Logger

	// RequestLimit bounds the body in bytes. Zero means
	// [DefaultRequestLimit].
	RequestLimit int64
}

Handler is the http.Handler exposing a Mux over HTTP.

func NewHandler 

func NewHandler() *Handler

NewHandler builds a Handler with a fresh Mux.

func (*Handler) ServeHTTP 

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements http.Handler.

type IntValue 

type IntValue int32

IntValue maps to <i4>.

func (IntValue) Kind 

func (IntValue) Kind() Kind

func (IntValue) MarshalXML 

func (v IntValue) MarshalXML(e *xml.Encoder, _ xml.StartElement) error

type Kind 

type Kind int

Kind identifies the concrete XML-RPC value carried by Value. 

const (
	KindNil Kind = iota
	KindInt
	KindBool
	KindString
	KindDouble
	KindDateTime
	KindBase64
	KindStruct
	KindArray
)

Supported value kinds. Order is stable.

func (Kind) String 

func (k Kind) String() string

String returns the XML token representing the kind.

type Member 

type Member struct {
	Name  string
	Value Value
}

Member is one entry in a StructValue.

type MethodCall 

type MethodCall struct {
	Method string
	Params []Value
}

MethodCall is a deserialised <methodCall>.

func DecodeCall 

func DecodeCall(r io.Reader) (*MethodCall, error)

DecodeCall reads a <methodCall> from r.

type MethodHandler 

type MethodHandler func(ctx context.Context, params []Value) (Value, error)

MethodHandler processes one XML-RPC method invocation.

type MethodResponse 

type MethodResponse struct {
	Params []Value
	Fault  *Fault
}

MethodResponse is a deserialised <methodResponse>. Exactly one of Params / Fault is populated.

func DecodeResponse 

func DecodeResponse(r io.Reader) (*MethodResponse, error)

DecodeResponse reads a <methodResponse> from r.

type Mux 

type Mux struct {
	// contains filtered or unexported fields
}

Mux routes XML-RPC method names to handlers. Safe for concurrent use.

func NewMux 

func NewMux() *Mux

NewMux returns an empty Mux.

func (*Mux) Dispatch 

func (m *Mux) Dispatch(ctx context.Context, method string, params []Value) (Value, error)

Dispatch invokes the handler registered for method.

func (*Mux) Handle 

func (m *Mux) Handle(method string, fn MethodHandler)

Handle registers fn for method, replacing any prior registration.

func (*Mux) HandleFallback 

func (m *Mux) HandleFallback(fn MethodHandler)

HandleFallback registers a catch-all handler.

func (*Mux) Has 

func (m *Mux) Has(method string) bool

Has reports whether method is registered.

func (*Mux) Methods 

func (m *Mux) Methods() []string

Methods returns the registered method names sorted ascending.

func (*Mux) RegisterSystemMethods 

func (m *Mux) RegisterSystemMethods()

RegisterSystemMethods wires system.listMethods, system.methodHelp and system.multicall, matching what HomeMatic clients expect.

type NilValue 

type NilValue struct{}

NilValue serialises as <value><nil/></value>.

func (NilValue) Kind 

func (NilValue) Kind() Kind

func (NilValue) MarshalXML 

func (NilValue) MarshalXML(e *xml.Encoder, _ xml.StartElement) error

type StringValue 

type StringValue string

StringValue maps to <string>.

func (StringValue) Kind 

func (StringValue) Kind() Kind

func (StringValue) MarshalXML 

func (v StringValue) MarshalXML(e *xml.Encoder, _ xml.StartElement) error

type StructValue 

type StructValue struct {
	Members []Member
}

StructValue is an ordered list of named members.

func AsStruct 

func AsStruct(v Value) (StructValue, bool)

AsStruct extracts a struct from v.

func (StructValue) Get 

func (s StructValue) Get(name string) (Value, bool)

Get returns the named member or (nil, false) if absent.

func (StructValue) Kind 

func (StructValue) Kind() Kind

func (StructValue) MarshalXML 

func (s StructValue) MarshalXML(e *xml.Encoder, _ xml.StartElement) error

type Value 

type Value interface {
	Kind() Kind
	MarshalXML(e *xml.Encoder, start xml.StartElement) error
}

Value is the sum type covering every XML-RPC value. Implementations serialise themselves including the wrapping <value>…</value>.

func DecodeValue 

func DecodeValue(d *xml.Decoder, start xml.StartElement) (Value, error)

DecodeValue reads a single <value>…</value> from d.

CCU clients emit two equivalent string forms; both are accepted:

  • <value><string>abc</string></value>
  • <value>abc</value>

func FromAny 

func FromAny(v any) Value

FromAny converts an arbitrary Go value (typically the result of json.Unmarshal into any) to its XML-RPC equivalent. Nil yields NilValue. Numeric types collapse to IntValue or DoubleValue; maps become StructValue sorted by key (deterministic output); slices become ArrayValue.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.