xapi

README

Background

I was issued a Webex Desk Pro as part of my day job. The first thing I wanted was use its customization/integreation support to Home Assistant so I could adjust my blinds and lighting as the day chanes right from my Desk Pro. The out of the box integreation options are JavaScript or Python SDKs and I played around with them but in the end Golang was the best fit for me.

Known Limitations

• Not all event and command types are currently implemented. Only enough for most of my current use cases.
• I only have access to a Desk Pro with integrator level access.
• This code is still a WIP so the API should NOT be considered stable.
• WebSocket only. No SSH transport.

Todo

• Unit Tests
• Better/More Examples
• Improve Docs
• Review that all optional fields are infact optional for things like Client.Alert.

Documentation

Index

• Variables
• type CallbackFunc
• type Client
  • func (c *Client) Alert(title string, text string, duration time.Duration) error
  • func (c *Client) Close() error
  • func (c *Client) Connect() error
  • func (c *Client) ConnectAndRun() error
  • func (c *Client) ConnectContext(ctx context.Context) error
  • func (c *Client) Get(path Path) (interface{}, error)
  • func (c *Client) Mute() error
  • func (c *Client) Prompt(title string, text string, options *[optionNumberOfChoices]string, ...) error
  • func (c *Client) Rating(title string, text string, ...) error
  • func (c *Client) Run() error
  • func (c *Client) SetWidgetValue(widgetID string, value interface{}) error
  • func (c *Client) Subscribe(path Path, callback CallbackFunc) (func() error, error)
  • func (c *Client) TextInput(text string, cb func(canceled bool, response string, err error), ...) error
  • func (c *Client) TextLine(text string, duration time.Duration) error
  • func (c *Client) UnMute() error
• type Command
• type JSONRPCError
  • func (e JSONRPCError) Error() string
• type Path
• type TextInputOption
  • func WithDuration(dur time.Duration) TextInputOption
  • func WithInputKeyboardHidden() TextInputOption
  • func WithInputText(text string) TextInputOption
  • func WithInputType(inputType TextInputType) TextInputOption
  • func WithPlaceholderText(text string) TextInputOption
  • func WithSubmitText(text string) TextInputOption
  • func WithTitle(text string) TextInputOption
• type TextInputType

Variables

var (
	// ErrInvalidCredentials is returned when authentication fails.
	ErrInvalidCredentials = errors.New("missing login or password")
	// ErrMissingChannel is returned when a response channel is not found for
	// a response that comes in.  This should not happen unless a channel is removed
	// due to timeout and the message comes in late.
	ErrMissingChannel = errors.New("missing response channel for request")
	// ErrMissingIDField is when a json response from the Webex device does not have an ID field
	// and thus you can't correlate what request this response fufills.
	ErrMissingIDField = errors.New("missing id field in response")
	// ErrNotConnected happens when you try and perform client operations without calling
	// one of the connect methods.
	ErrNotConnected = errors.New("not connected")
	// ErrInvalidMsg is returned when an invalid json message type is received from the Webex device.
	ErrInvalidMsg = errors.New("invalid message")
	// ErrUnknownResponse is returned when a jsonrpc2 response comes in with an unknown data type.
	ErrUnknownResponse = errors.New("unknown response")
	// ErrUnsupportedMsg is returned when a unhandled jsonrpc2 occurs.  Currently this only happens
	// when a jsonrpc2 Request Message comes in from the server.
	ErrUnsupportedMsg = errors.New("unsupported jsonrpc2 message")
	// ErrMissingData is returned when we parse the response json struct for the jpath and
	// it returns nothing.
	ErrMissingData = errors.New("missing response data")
	// ErrMissingCallback is returned when we find a response in the callback tree but its missing
	// I don't think would ever happen in the real world.
	ErrMissingCallback = errors.New("missing callback")
)

Types

type CallbackFunc

type CallbackFunc func(data []interface{})

CallbackFunc is the func signature for callbacks for events.

type Client

type Client struct {
	User     string
	Password string
	Insecure bool
	URL      string

	OnConnectFunc func(*Client)
	// contains filtered or unexported fields
}

Client is the main client that handles all communication to/from the WebEx device.

func (*Client) Alert

func (c *Client) Alert(title string, text string, duration time.Duration) error

Alert displays an Alert in the UI of the device, this shows up in the upper right corner on a Desk Pro.

func (*Client) Close

func (c *Client) Close() error

Close and disconnect from the Webex.

func (*Client) Connect

func (c *Client) Connect() error

Connect to the Webex device.

func (*Client) ConnectAndRun

func (c *Client) ConnectAndRun() error

ConnectAndRun is a helper to connect and start the run loop.

func (*Client) ConnectContext

func (c *Client) ConnectContext(ctx context.Context) error

ConnectContext connect to the Webex device with a context.

func (*Client) Get

func (c *Client) Get(path Path) (interface{}, error)

Get retrieve the value of a setting, status or UI element.

func (*Client) Mute

func (c *Client) Mute() error

func (*Client) Prompt

func (c *Client) Prompt(title string, text string,
	options *[optionNumberOfChoices]string, cb func(string, error)) error

Prompt displays a UI prompt with multiple options. TODO Duration and title are optional. TODO we should also have a callback for the UI prompt going away with a timeout.

func (*Client) Rating

func (c *Client) Rating(title string, text string, callback func(canceled bool, value int64, err error)) error

Rating opens a '5 star' rating dialog on the Webex device. A user can cancel the prompt or choose a number of stars. The rating is returned as an int64.

func (*Client) Run

func (c *Client) Run() error

Run is the client's main run loop. This blocks till disconnect or a non recoverable error happens.

func (*Client) SetWidgetValue

func (c *Client) SetWidgetValue(widgetID string, value interface{}) error

SetWidgetValue updates a UI widget with a new value.

func (*Client) Subscribe

func (c *Client) Subscribe(path Path, callback CallbackFunc) (func() error, error)

Subscribe lets you subscribe to event, UI or status change events of the Webex device.

func (*Client) TextInput

func (c *Client) TextInput(text string, cb func(canceled bool, response string, err error), opts ...TextInputOption) error

TextInput lets you prompt a user for a free form text string. When the user submits the text the callback is called with the response passed in.

func (*Client) TextLine

func (c *Client) TextLine(text string, duration time.Duration) error

TextLine displays text centered on the screen. There is no way to dismiss this from the UI and requires the timeout to be a non zero value, or to be cleared with a call to TextLineClear.

func (*Client) UnMute

func (c *Client) UnMute() error

type Command

type Command string

Command is a JsonRPC2 Method. Currently this is exposed in the event that we do not have everything defined in here and we can set these... though there is no way to actually call them directly.

type JSONRPCError

type JSONRPCError struct {
	Code    float64
	Data    interface{}
	Message string
}

JSONRPCError represents the JsonRPC2 Error message in a more golang friendly way rather than just a response type.

func (JSONRPCError) Error

func (e JSONRPCError) Error() string

type Path

type Path string

Path represents the xapi path in the system. It is a space delimited field that can be converted to jpath, parameters for a Get or the path to listen to for events. If the needed Path for your use case is not implemented here its possible to just define a new path and use all the library functionality with that new path.

const (
	Status                                    Path = "Status"
	StatusSystemUnit                          Path = "Status SystemUnit"
	StatusSystemUnitStateNumberOfActiveCalls  Path = "Status SystemUnit State NumberOfActiveCalls"
	StatusAudioVolumeLevel                    Path = "Status Audio Volume"
	StatusAudioMicrophonesMute                Path = "Status Audio Microphones Mute"
	StatusVideoInputMainVideoMute             Path = "Status Video Input MainVideoMute"
	Event                                     Path = "Event"
	EventUserInterface                        Path = "Event UserInterface"
	EventUserInterfaceExtension               Path = "Event UserInterface Extensions"
	EventUserInterfaceExtensionsEvent         Path = "Event UserInterface Extensions Event"
	EventUserInterfaceExtensionsEventReleased Path = "Event UserInterface Extensions Event Released"
	EventUserInterfaceExtensionsEventClicked  Path = "Event UserInterface Extensions Event Pressed"
	EventUserInterfaceExtensionsEventChanged  Path = "Event UserInterface Extensions Event Changed"
	EventUserInterfaceWidgetAction            Path = "Event UserInterface Extensions Widget Action"
	EventUserInterfacePanelClicked            Path = "Event UserInterface Extensions Panel Clicked"
	EventUserInterfacePanelClose              Path = "Event UserInterface Extensions Panel Close"
	EventUserInterfacePanelOpen               Path = "Event UserInterface Extensions Panel Open"
	EventUserInterfacePromptResponse          Path = "Event UserInterface Message Prompt Response"
	EventUserInterfaceRatingResponse          Path = "Event UserInterface Message Rating Response"
	EventUserInterfaceTextInputResponse       Path = "Event UserInterface Message TextInput Response"
	EventUserInterfaceTextInputResponseClear  Path = "Event UserInterface Message TextInput Clear"
	EventUserInterfaceMessageAlertCleared     Path = "Event UserInterface Message Alert Cleared"
	EventUserInterfaceMessageRatingCleared    Path = "Event UserInterface Message Rating Cleared"
	EventUserInterfaceMessageTextLineCleared  Path = "Event UserInterface Message TextLine Cleared"
	EventShutdown                             Path = "Event Shutdown"
	EventIncomingCallIndication               Path = "Event IncomingCallIndication"
)

type TextInputOption

type TextInputOption func(map[string]interface{})

TextInputOption is a func signature for modifying all the various options you can set for the TextInput UI.

func WithDuration

func WithDuration(dur time.Duration) TextInputOption

WithDuration lets you specify a duration for how long a TextInput is displayed. The default value is 0 which means you need to either manually clear it,.

func WithInputKeyboardHidden

func WithInputKeyboardHidden() TextInputOption

WithInputKeyboardHidden lets you hide the keyboard when the TextInput dialog is on the screen.

func WithInputText

func WithInputText(text string) TextInputOption

WithInputText lets you specify the text description of what the input box is for.

func WithInputType

func WithInputType(inputType TextInputType) TextInputOption

WithInputType what type of input box are we looking for.

func WithPlaceholderText

func WithPlaceholderText(text string) TextInputOption

WithPlaceholderText text is text that populates the box. When you start intputing text it will clear this.

func WithSubmitText

func WithSubmitText(text string) TextInputOption

WithSubmitText this sets the default text that lets you submit. You can clear it out and add your own information.

func WithTitle

func WithTitle(text string) TextInputOption

WithTitle sets the title for a TextInput. Default is blank.

type TextInputType

type TextInputType string

TextInputType is the more domain specific element to prompt a user for such as PIN or Password etc. It helps decide which KeyBoard to show as well as if input should be masked or not.

const (
	// SingleLine TextInput type.
	SingleLine TextInputType = "SingleLine"
	// Numeric TextInput type, brings up numeric friendly keyboard.
	Numeric TextInputType = "Numeric"
	// Password TextInput type.  Masked input with alphanumeric keyboard.
	Password TextInputType = "Password"
	// PIN TextInput type.  Masked input with numeric friendly keyboard.
	PIN TextInputType = "PIN"
)