Documentation

Overview

    Package jid implements the XMPP address format.

    XMPP addresses, more often called "JID's" (Jabber ID's) for historical reasons, comprise three parts: The localpart represents a specific user account, the domainpart is the domain, host name, or IP address of a server hosting the account, and the resourcepart which represents a specific client connected to an account (eg. the users phone or a web browser). Only the domainpart is required, and together they are formatted like an email with the resourcepart appended after a forward slash. For example, the following are all valid JIDs:

    shakespeare@example.net
    shakespeare@example.net/phone-b5c93ded
    example.net
    

    The first represents the account "shakespeare" on the service "example.net", the second represents a specific phone connected to that account, and the third represents the server running the service at example.net. This means that clients connected to the XMPP network are individually and globally addressable.

    The jid package also implements the escaping mechanism defined in XEP-0106: JID Escaping. This can be used to expand the supported characters in the username of a JID.

    Be advised: This API is still unstable and is subject to change.

    Index

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    func SplitString

    func SplitString(s string) (localpart, domainpart, resourcepart string, err error)

      SplitString splits out the localpart, domainpart, and resourcepart from a string representation of a JID. The parts are not guaranteed to be valid, and each part must be 1023 bytes or less.

      Types

      type JID

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

        JID represents an XMPP address (Jabber ID) comprising a localpart, domainpart, and resourcepart. All parts of a JID are guaranteed to be valid UTF-8 and will be represented in their canonical form which gives comparison the greatest chance of succeeding.

        func MustParse

        func MustParse(s string) JID

          MustParse is like Parse but panics if the JID cannot be parsed. It simplifies safe initialization of JIDs from known-good constant strings.

          func New

          func New(localpart, domainpart, resourcepart string) (JID, error)

            New constructs a new JID from the given localpart, domainpart, and resourcepart.

            func Parse

            func Parse(s string) (JID, error)

              Parse constructs a new JID from the given string representation.

              func (JID) Bare

              func (j JID) Bare() JID

                Bare returns a copy of the JID without a resourcepart. This is sometimes called a "bare" JID.

                func (JID) Copy

                func (j JID) Copy() JID

                  Copy makes a copy of the given JID. j.Equal(j.Copy()) will always return true.

                  func (JID) Domain

                  func (j JID) Domain() JID

                    Domain returns a copy of the JID without a resourcepart or localpart.

                    func (JID) Domainpart

                    func (j JID) Domainpart() string

                      Domainpart gets the domainpart of a JID (eg. "example.net").

                      func (JID) Equal

                      func (j JID) Equal(j2 JID) bool

                        Equal performs an octet-for-octet comparison with the given JID.

                        func (JID) Localpart

                        func (j JID) Localpart() string

                          Localpart gets the localpart of a JID (eg "username").

                          func (JID) MarshalXML

                          func (j JID) MarshalXML(e *xml.Encoder, start xml.StartElement) (err error)

                            MarshalXML satisfies the xml.Marshaler interface and marshals the JID as XML chardata.

                            func (JID) MarshalXMLAttr

                            func (j JID) MarshalXMLAttr(name xml.Name) (xml.Attr, error)

                              MarshalXMLAttr satisfies the xml.MarshalerAttr interface and marshals the JID as an XML attribute.

                              func (JID) Network

                              func (JID) Network() string

                                Network satisfies the net.Addr interface by returning the name of the network ("xmpp").

                                func (JID) Resourcepart

                                func (j JID) Resourcepart() string

                                  Resourcepart gets the resourcepart of a JID.

                                  func (JID) String

                                  func (j JID) String() string

                                    String converts an JID to its string representation.

                                    func (*JID) UnmarshalXML

                                    func (j *JID) UnmarshalXML(d *xml.Decoder, start xml.StartElement) (err error)

                                      UnmarshalXML satisfies the xml.Unmarshaler interface and unmarshals the JID from the elements chardata.

                                      func (*JID) UnmarshalXMLAttr

                                      func (j *JID) UnmarshalXMLAttr(attr xml.Attr) error

                                        UnmarshalXMLAttr satisfies the xml.UnmarshalerAttr interface and unmarshals an XML attribute into a valid JID (or returns an error).

                                        func (JID) WithDomain

                                        func (j JID) WithDomain(domainpart string) (JID, error)

                                          WithDomain returns a copy of the JID with a new domainpart. This elides validation of the localpart and resourcepart.

                                          func (JID) WithLocal

                                          func (j JID) WithLocal(localpart string) (JID, error)

                                            WithLocal returns a copy of the JID with a new localpart. This elides validation of the domainpart and resourcepart.

                                            func (JID) WithResource

                                            func (j JID) WithResource(resourcepart string) (JID, error)

                                              WithResource returns a copy of the JID with a new resourcepart. This elides validation of the localpart and domainpart.

                                              type Transformer

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

                                                Transformer implements the transform.Transformer and transform.SpanningTransformer interfaces.

                                                For more information see golang.org/x/text/transform or the predefined Escape and Unescape transformers.

                                                var (
                                                	// Escape is a transform that maps escapable runes to their escaped form.
                                                	Escape Transformer = Transformer{escapeMapping{}}
                                                
                                                	// Unescape is a transform that maps valid escape sequences to their unescaped
                                                	// form.
                                                	Unescape Transformer = Transformer{unescapeMapping{}}
                                                )

                                                  Transformations defined in XEP-0106: JID Escaping.

                                                  func (Transformer) Bytes

                                                  func (t Transformer) Bytes(b []byte) []byte

                                                    Bytes returns a new byte slice with the result of applying t to b.

                                                    func (Transformer) Reset

                                                    func (t Transformer) Reset()

                                                      Reset implements the transform.Transformer interface.

                                                      func (Transformer) Span

                                                      func (t Transformer) Span(src []byte, atEOF bool) (n int, err error)

                                                        Span implements the transform.SpanningTransformer interface.

                                                        func (Transformer) String

                                                        func (t Transformer) String(s string) string

                                                          String returns a string with the result of applying t to s.

                                                          func (Transformer) Transform

                                                          func (t Transformer) Transform(dst, src []byte, atEOF bool) (nDst, nSrc int, err error)

                                                            Transform implements the transform.Transformer interface.

                                                            type Unsafe

                                                            type Unsafe struct {
                                                            	JID
                                                            }

                                                              Unsafe is a JID that has not had any normalization, length checks, UTF-8 validation, or other safety measures applied.

                                                              It can be a source of bugs, or even a security risk, if used improperly.

                                                              func NewUnsafe

                                                              func NewUnsafe(localpart, domainpart, resourcepart string) Unsafe

                                                                NewUnsafe constructs a new unsafe JID. For more information, see the Unsafe type.

                                                                func ParseUnsafe

                                                                func ParseUnsafe(s string) (Unsafe, error)

                                                                  ParseUnsafe constructs a new unsafe JID from a string. For more information, see the Unsafe type.