ninchat

README

Go client package for the Ninchat API. Compatible with GopherJS (see also ninchat-js). Uses Gorilla WebSocket package with native Go.

The implementation uses few standard packages directly in order to reduce generated JavaScript code size. Subsets of encoding/json, math/rand, net/http and time packages are wrapped for native Go, and reimplemented using web browser APIs for GopherJS.

Documentation

Overview

Ninchat API connection library.

https://ninchat.com/api

Index

• Variables
• type Action
  • func (a *Action) GetID() (id int64, err error)
  • func (a *Action) String() (s string)
• type Caller
  • func (caller *Caller) Call(action *Action) (events []*Event, err error)
• type Event
  • func Call(action *Action) (events []*Event, err error)
  • func (e *Event) Array(param string) (v []interface{}, ok bool)
  • func (e *Event) Bool(param string) (v bool)
  • func (e *Event) Float64(param string) (v float64, ok bool)
  • func (e *Event) Int(param string) (v int, ok bool)
  • func (e *Event) Int64(param string) (v int64, ok bool)
  • func (e *Event) Map(param string) (v map[string]interface{}, ok bool)
  • func (e *Event) Str(param string) (v string, ok bool)
  • func (e *Event) String() (s string)
• type Frame
• type Session
  • func (s *Session) Close()
  • func (s *Session) Open()
  • func (s *Session) Send(action *Action) (err error)
  • func (s *Session) SetParams(params map[string]interface{})

Variables

var DefaultUserAgent = fmt.Sprintf("ninchat-go/1 (%s; %s)", runtime.GOOS, runtime.GOARCH)

Types

type Action

type Action struct {
	Params  map[string]interface{}
	Payload []Frame
	OnReply func(*Event)
	// contains filtered or unexported fields
}

Action

func (*Action) GetID

func (a *Action) GetID() (id int64, err error)

GetID returns the action_id if Send has been called and it generated one.

func (*Action) String

func (a *Action) String() (s string)

String returns the action's name.

type Caller

type Caller struct {
	// Header fields to be added to HTTP requests.  The keys must be in
	// canonical format (see https://golang.org/pkg/net/http/#CanonicalHeaderKey).
	Header map[string][]string

	Address string
}

func (*Caller) Call

func (caller *Caller) Call(action *Action) (events []*Event, err error)

type Event

type Event struct {
	Params    map[string]interface{}
	Payload   []Frame
	LastReply bool
}

Event

func Call

func Call(action *Action) (events []*Event, err error)

Call the sessionless API.

If the action's OnReply callback is set, it will be called with the result events, unless an error occurs.

https://ninchat.com/api#sessionless-http-calling

func (*Event) Array

func (e *Event) Array(param string) (v []interface{}, ok bool)

Array looks up an array parameter.

func (*Event) Bool

func (e *Event) Bool(param string) (v bool)

Bool looks up a boolean parameter. A boolean parameter is considered false when it is nil or not set.

func (*Event) Float64

func (e *Event) Float64(param string) (v float64, ok bool)

Float64 looks up a numeric parameter.

func (*Event) Int

func (e *Event) Int(param string) (v int, ok bool)

Int looks up a numeric parameter and converts it to an integer.

func (*Event) Int64

func (e *Event) Int64(param string) (v int64, ok bool)

Int64 looks up a numeric parameter and converts it to a 64-bit integer.

func (*Event) Map

func (e *Event) Map(param string) (v map[string]interface{}, ok bool)

Map looks up an object parameter.

func (*Event) Str

func (e *Event) Str(param string) (v string, ok bool)

Str looks up a string parameter.

func (*Event) String

func (e *Event) String() (s string)

String returns the event's name.

type Frame

type Frame []byte

Frame

type Session

type Session struct {
	// OnSessionEvent is the session creation handler.  It will be invoked with
	// a "session_created" or an "error" event.
	//
	// If another "session_created" event is received, it means that the previous
	// session was lost, and a new one was established automatically.
	//
	// If an "error" event is received, it means that a new session can't be
	// established without intervention.  The client code must call SetParams to
	// supply new credentials, unless it decides to Close.
	//
	OnSessionEvent func(*Event)

	// OnEvent is the handler for in-session events.
	//
	// "error" events received via this callback are not fatal.
	//
	OnEvent func(*Event)

	// OnClose is an optional session closure handler.  It will be invoked
	// after a Close call has been fully processed.  It won't be invoked if an
	// "error" event is received via OnSessionEvent (unless SetParams is called
	// again).
	//
	OnClose func()

	// OnConnState is an optional connection state change monitor.  It will be
	// called with one of the following strings:
	//
	// - "connecting"
	// - "connected"
	// - "disconnected"
	//
	OnConnState func(state string)

	// OnConnActive is an optional connection activity monitor.  It will be
	// called (approximately) when data is received on the underlying network
	// connection.
	OnConnActive func()

	// OnLog is an optional message logger.
	OnLog func(fragments ...interface{})

	// Header fields to be added to HTTP requests.  The keys must be in
	// canonical format (see https://golang.org/pkg/net/http/#CanonicalHeaderKey).
	Header map[string][]string

	Address string

	DisableLongPoll bool
	// contains filtered or unexported fields
}

Session hides the details of API connection management. It needs to be initialized by setting at least OnSessionEvent and OnEvent, and calling SetParams. After that the Open method is used to make a connection to the server. Finally, the Close method disconnects from the server.

func (*Session) Close

func (s *Session) Close()

Close the session on the server.

func (*Session) Open

func (s *Session) Open()

Open creates a session on the server.

func (*Session) Send

func (s *Session) Send(action *Action) (err error)

Send an action.

To send an action without an "action_id" parameter, specify it as nil. Otherwise an "action_id" is generated automatically.

If "action_id" is used and the action's OnReply callback is set, it will be called when a reply event is received. If the Session object is closed before a reply is received, OnReply will be called with a nil argument.

With specific actions that cause multiple reply events, the OnReply callback will be called for each event until the final event. Only the last event will have the LastReply member set.

func (*Session) SetParams

func (s *Session) SetParams(params map[string]interface{})

SetParams sets initial action parameters. The initial action is "create_session" by default, or "resume_session" if the "session_id" parameter is set. If Open has already been called, this takes effect when a session is lost.