ibb

Documentation

Overview

Package ibb implements data transfer with XEP-0047: In-Band Bytestreams.

In-band bytestreams (IBB) are a bidirectional data transfer mechanism that can be used to send small files or transfer other low-bandwidth data. Because IBB uses base64 encoding to send the binary data, it is extremely inefficient and should only be used as a fallback or last resort.

Index

• Constants
• func Handle(h *Handler) mux.Option
• type Conn
  • func (c *Conn) Close() error
  • func (c *Conn) Flush() error
  • func (c *Conn) LocalAddr() net.Addr
  • func (c *Conn) Read(b []byte) (n int, err error)
  • func (c *Conn) RemoteAddr() net.Addr
  • func (c *Conn) SID() string
  • func (c *Conn) SetDeadline(t time.Time) error
  • func (c *Conn) SetReadBuffer(max int)
  • func (c *Conn) SetReadDeadline(t time.Time) error
  • func (c *Conn) SetWriteDeadline(t time.Time) error
  • func (c *Conn) Size() int
  • func (c *Conn) Stanza() string
  • func (c *Conn) Write(b []byte) (n int, err error)
• type Handler
  • func (h *Handler) HandleIQ(iq stanza.IQ, t xmlstream.TokenReadEncoder, start *xml.StartElement) error
  • func (h *Handler) HandleMessage(msg stanza.Message, t xmlstream.TokenReadEncoder) error
  • func (h *Handler) Listen(s *xmpp.Session) *Listener
  • func (h *Handler) Open(ctx context.Context, s *xmpp.Session, to jid.JID) (*Conn, error)
  • func (h *Handler) OpenIQ(ctx context.Context, iq stanza.IQ, s *xmpp.Session, ack bool, blockSize uint16, ...) (*Conn, error)
• type Listener
  • func (l *Listener) Accept() (net.Conn, error)
  • func (l *Listener) Addr() net.Addr
  • func (l *Listener) Close() error
  • func (l *Listener) Expect(ctx context.Context, from jid.JID, sid string) (net.Conn, error)

Constants

const (
	// BlockSize is the default block size used if an IBB stream is opened with no
	// block size set.
	// Because IBB base64 encodes the underlying data, the actual data transfered
	// per stanza will be roughly twice the blocksize.
	BlockSize = 1 << 11

	// MaxBufferSize is the default maximum size the internal buffer will be
	// allowed to grow before sending back an error telling the other side to wait
	// before transmitting more data.
	// if a block size that is larger than maxbuffersize is used the default
	// maximum buffer size changes to be twice the block size.
	MaxBufferSize = 1 << 18
)

const NS = `http://jabber.org/protocol/ibb`

NS is the XML namespace used by IBB, provided as a convenience.

Functions

func Handle

func Handle(h *Handler) mux.Option

Handle is an option that registers a handler for all the correct stanza types and payloads.

Types

type Conn

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

Conn is an IBB stream. Writes to the stream are buffered up to the blocksize before being transmitted.

func (*Conn) Close

func (c *Conn) Close() error

Close closes the connection. Any blocked Read or Write operations will be unblocked and return errors. If the write buffer contains data it will be flushed.

func (*Conn) Flush

func (c *Conn) Flush() error

Flush writes any buffered data to the underlying io.Writer. This may result in data transfer less than the block size.

func (*Conn) LocalAddr

func (c *Conn) LocalAddr() net.Addr

LocalAddr returns the local network address of the underlying XMPP session.

func (*Conn) Read

func (c *Conn) Read(b []byte) (n int, err error)

Read reads data from the IBB stream. Read can be made to time out and return an Error with Timeout() == true after a fixed time limit; see SetDeadline and SetReadDeadline.

func (*Conn) RemoteAddr

func (c *Conn) RemoteAddr() net.Addr

RemoteAddr returns the remote network address of the IBB stream.

func (*Conn) SID

func (c *Conn) SID() string

SID returns a unique session ID for the connection.

func (*Conn) SetDeadline

func (c *Conn) SetDeadline(t time.Time) error

SetDeadline sets the read and write deadlines associated with the connection. It is equivalent to calling both SetReadDeadline and SetWriteDeadline.

A deadline is an absolute time after which I/O operations fail with a timeout (see type Error) instead of blocking. The deadline applies to all future and pending I/O, not just the immediately following call to Read or Write. After a deadline has been exceeded, the connection can be refreshed by setting a deadline in the future.

An idle timeout can be implemented by repeatedly extending the deadline after successful Read or Write calls.

A zero value for t means I/O operations will not time out.

func (*Conn) SetReadBuffer

func (c *Conn) SetReadBuffer(max int)

SetReadBuffer sets the maximum size the internal buffer will be allowed to grow to before sending back an error telling the other side to wait before transmitting more data. The actual buffer is never shrunk, even if a maximum size is set that is less than the current length of the buffer. Instead, errors will be returned for incoming data until enough data has been read from the buffer to shrink it below the new max size. If max is zero or less buffer growth is not limited. If max is less than the block size it is ignored and the block size is used instead.

func (*Conn) SetReadDeadline

func (c *Conn) SetReadDeadline(t time.Time) error

SetReadDeadline sets the deadline for future Read calls and any currently-blocked Read call. A zero value for t means Read will not time out.

func (*Conn) SetWriteDeadline

func (c *Conn) SetWriteDeadline(t time.Time) error

SetWriteDeadline sets the deadline for future Write calls and any currently-blocked Write call. Even if write times out, it may return n > 0, indicating that some of the data was successfully written. A zero value for t means Write will not time out.

func (*Conn) Size

func (c *Conn) Size() int

Size returns the maximum blocksize for data transmitted over the stream. Note that individual packets sent on the stream may be less than the block size even if there is enough data to fill the block.

func (*Conn) Stanza

func (c *Conn) Stanza() string

Stanza returns the carrier stanza type ("message" or "iq") for payloads received by the IBB session.

func (*Conn) Write

func (c *Conn) Write(b []byte) (n int, err error)

Write writes data to the IBB stream. Write can be made to time out and return an Error with Timeout() == true after a fixed time limit; see SetDeadline and SetWriteDeadline.

type Handler

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

Handler is an xmpp.Handler that handles multiplexing of bidirectional IBB streams.

func (*Handler) HandleIQ

func (h *Handler) HandleIQ(iq stanza.IQ, t xmlstream.TokenReadEncoder, start *xml.StartElement) error

HandleIQ implements mux.IQHandler.

func (*Handler) HandleMessage

func (h *Handler) HandleMessage(msg stanza.Message, t xmlstream.TokenReadEncoder) error

HandleMessage implements mux.MessageHandler.

func (*Handler) Listen

func (h *Handler) Listen(s *xmpp.Session) *Listener

Listen creates a listener that accepts incoming IBB requests.

If a listener has already been created for the given session it is returned unaltered.

func (*Handler) Open

func (h *Handler) Open(ctx context.Context, s *xmpp.Session, to jid.JID) (*Conn, error)

Open attempts to create a new IBB stream on the provided session.

func (*Handler) OpenIQ

func (h *Handler) OpenIQ(ctx context.Context, iq stanza.IQ, s *xmpp.Session, ack bool, blockSize uint16, sid string) (*Conn, error)

OpenIQ is like Open except that it allows you to customize the IQ and other properties of the session initialization. Changing the type of the IQ has no effect.

type Listener

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

Listener is an implementation of net.Listener that is used to accept incoming IBB streams.

func (*Listener) Accept

func (l *Listener) Accept() (net.Conn, error)

Accept waits for the next incoming IBB stream and returns the connection. If the listener is closed by either end pending Accept calls unblock and return an error.

func (*Listener) Addr

func (l *Listener) Addr() net.Addr

Addr returns the local address for which this listener is accepting connections.

func (*Listener) Close

func (l *Listener) Close() error

Close stops listening and causes any pending Accept calls to unblock and return an error. Already accepted connections are not closed.

func (*Listener) Expect

func (l *Listener) Expect(ctx context.Context, from jid.JID, sid string) (net.Conn, error)

Expect is like Accept except that it accepts a specific session that has been negotiated out-of-band. If Accept and Expect are both waiting on connections, Expect will take precedence. If Expect is called twice for the same session the original call will be canceled and return a context error and the new Expect call will take over.