If you have bugs, please use bugzilla at http://bugs.jabber.org Register them in the jabberoo section.

Download the COM library zip file here

IJabberSession

This is the main interface that you should use to communicate to the Jabber server. This interface stores all of the configuration information and encapsulates all of the server communication and XML details.

Properties

• Server [Str]- Hostname of the jabber server to connect to.
• Username [Str]- Username to use on the server.
• Password [Str]- password for this account
• Resource [Str]- A unique resource for this connection
• MyJID [Str] - The currently active JID for the authenticated account + resource.
• ForwardMsgs [Bool] - Should offline messages be forwarded someplace else?
• ForwardTo [Str] - JID (must include a resource) where offline messages should be forwareded to.
• OfflineStatus [Str] - Status to show when offline.
• Priority [Int]- A priority level for this client connection (1-10)
• Available [Bool] - Is the user available for msgs or not?
• ShowType [JabberShowType] - A "Show" style to tell other clients your current status. Can be: jshowNone (Default), jshowChat, jshowAway, jshowNA, jshowDND.
• Status [Str] - Current status like "Working" or "At Lunch"
• Active [Bool, Read Only] - Are we connected and authenticated??
• Roster [IJabberRoster] - Contains all roster information.
• Agents [IJabberAgents] - Contains all agent information.
• XMLRepository [IXMLRepository] - A pointer to the complete XML tag repository for the connection. See below for more details.
• LastErrorCode [Str] - Returns a string containing the last error code received from the server.
• ProxyServer [Str] - Name of the Proxy Server to connect to.
• ProxyPort [Int] - Port number to use when connecting to the Proxy Server.
• ProxyUser [Str] - Username to use when authenticating to the Proxy Server.
• ProxyPassword [Str] - Password to use when authenticating to the Proxy Server.
• ProxyMethod [JabberProxyType] - Type of Proxy. (jproxyNone, jproxySOCKS4, jproxySOCKS5)

Methods

CreateMsg: IJabberMsg

A Class Factory method that creates a new JabberMsg Object and returns an interface to that object.

CreateIQ: IJabberIQ

A Class Factory method that creates a new JabberIQ Object and returns an interface to that object.

CreateXMLTag: IXMLTag

A Class Factory method that creates a new XMLTag Object and returns an interface to that object.

DoConnect(NewUser: boolean; AuthType: JabberAuthType)

This method will attempt to connect to the specified server, authenticate the user, and send our presence to the server. Newuser specifies whether or not you want to create a new user account on the specified server.

The JabberAuthType enum type allows you to specify how you want JabberCOM to send the password. Use either jatPlainText to send the normal un-encrypted password directly over the wire. Use jatDigest to send a hash to the server. This DOES NOT send the plain text password over the wire.

DoDisconnect(Immediate: boolean)

Disconnect from the server. Normal operation is Immediate=False, this sends a end stream packet to the server and the server is then responsible for closing the socket. If you send true, JabberCOM just closes the socket, and does all the normal cleanup without waiting for anything from the server. This is useful to send after socket/COMM errors.

SendMessage(Msg: IJabberMsg)

Send a message to a specific user using the IJabberMsg interface.

SendIQ(IQ: IJabberIQ)

Send a JabberIQ back to the server.

SendPresence(JID: String; PresType: JabberPresenceType; Status: string; XTag: IXMLTag)

Send a presence [subscription] to someone.

SendMyPresence

Send your current presence info to the server. Note that also setting the Status or Available properties AUTOMATICALLY sends you new presence back to the server.

GetPres(jid: String; resource: string; Primary: Boolean): IJabberPres

This method is used to fetch presence objects off of the Presence Database. To find if someone is online, use a blank resource, and fetch their primary resource. See below for details about the IJabberPres object. Successive calls to GetPres with the same jid, blank resource, and primary = false, will iterate through the presence database and provide you with all of the user's presence objects.

SendXML(txt: String)

send some raw text to the server.

Events

OnConnect

Fires after the server connection has been made and the username/pass correctly authenticated.

OnDisconnect

Fires when the connection is disconnected or is dropped.

OnAuthError(txt: string)

Fires when a problem occurs during authentication. Correct the username/pass and possibly the resource, and try Connect again. Txt will most likely contain an explaination of the error.The Error Code received from the server will be stored in the LastErrorCode variable.

OnCommError(txt: string)

General communication error. Check the text for more info. Could be a XML error or a communiction error.

OnQueryError(txt: string; FromJID: string; Tag: IXMLTag)

An error occured during a <iq> query. Txt should contain the error info returned from the server. The Error Code received from the server will be stored in the LastErrorCode variable. The Tag variable contains an interface to the entire XML tag received.

OnRosterStart

Signals the start of roster processing. Expect 0, 1 or more OnRosterItem events after this event.

OnRosterItem(Item: IJabberRosterItem)

A new roster item has been received. This is ideally the place to display the item in some GUI, or deal with it internally. This event is not always preceded by a OnRosterStart event... "single" OnRosterItem events can occur when the server changes something in the roster item and sends it back to you (aka, a Roster Push).

OnRosterEnd

Main roster processing has finished.

OnAgentsStart

We have started to receive an agents listing.

OnAgentItem(Agent: IJabberAgentItem; iqID: string)

We received an agent. The interface to the agent is passed. The ID string passed is the ID from the iq tag. Use this to "direct" incoming events in your client.

OnAgentsEnd

Agents list has finished processing

OnMessage(Msg: IJabberMsg; Tag: IXMLTag)

A message has been received. Use the IJabberMsg interface to get the details of the message. The tag object passed is a IXMLTag object which contains all of the actual XML Elements in this tag. Use it for dealing with special 'x' tags are looking for something in the low level message data/text.

OnPresence(PresJID: string; Available: Boolean; InRoster: boolean; Tag: IXMLTag)

This event fires when we receive a presence item from the server. We get the JID, whether the user is available or not, and whether or not they are in our roster.

OnSubscriptionRequest(FromJID: string; SubType: string)

Someone is sending us _some_ kind of subscription request.. could be 'subscribe' or 'unsubscribe'.

OnSubscriptionApproved(FromJID: string)

A user granted our request to subscribe to their presence information. The server will automatically update our roster, and send us presence info for this user.

OnSubscriptionDenied(FromJID: string)

We requested to subscribe to someone's presence information and they said 'no'.

OnXML(Direction: int; txt: String)

This event occurs whenever xml is either sent to or recieved from the server over the socket connection. Direction = (0) means text is coming in from the server, while (1) means text is being sent from the client to the server. This event is essential for debugging and trouble- shooting.

OnJabberIQ(namespace; string; IQ: IJabberIQ)

This event fires whenever we recieve an 'iq' tag. The associated JabberIQ tag is passed along with the namespace for the query tag. Only "handled" namespaces will fire this event. This includes jabber:iq:register.

OnUnhandledQuery(Namespace: string; Tag: IXMLTag)

Any iq or query tags that are received, but are not handled explicityly fire this event and pass the entire XML tag object back to the client.

OnXMLTag(Tag: IXMLTag)

This is a totally generic "catch-all" event that will fire after EVERY tag is parsed after it is received over the socket. The parsed tag is passed as a parameter. This occurs after any other processing has already occurred by JabberCOM.

OnVersionGet(FromJID: String; Tag: IXMLTag)

This event is fired whenever someone sends you a request for your CTCP version information. (jabber:iq:version namespace). To respond, create and send a JabberIQ object back to the sender adding the appropriate fields.

OnVersionResult(FromJID, AppName, AppVer, OS: String; Tag: IXMLTag)

This event is fired when you receive results from a CTCP Version query. Just display the information passed back.

OnTimeGet(FromJID: Tag:IXMLTag)

Similar to the OnVersionGet event. Create and send back a JabberIQ which uses the jabber:iq:time fields. This namespace is also used to "ping" poeple, so almost all clients should respond to it.

OnTimeResults(FromJID, Display: string; Tag: IXMLTag)

Fired when we get results from a CTCP Time query from another client. Display contains the localized way of representing the date/time.

OnSearchFields(Tag: IXMLTag)

Occurs after you do a IJabberAgentItem.GetSearch call. The resulting tag contains the iq tag which contains all of the fields.

OnSearchResult(JID: string; IQ: IJabberIQ)

This event fires for EACH "record" that is returned in a set of search results. The JabberIQ object will have all of the fields inside of it, and the JID is the JID for that record.

OnSearchEnd

This event fires to tell us we have received all of the search results.

OnGetOOB(FromJID, URL, Desc: String; Tag: IXMLTag)

This event is fired when someone tries to send you a file or URL.

---

IJabberRoster

This interface contains all the information in and about the roster.

Properties

• Count [int] - How many items are in the Roster?
• Items[index: int] - Return a specific IJabberRosterItem (see below for more interface details on Roster Items).
• Session - Returns the IJabberSession which this roster is connected to.

Methods

Add(NewJID: string; Nick: string): IJabberRosterItem

This method allows you to add a new item to the internal roster. This does not actually send anything to the server. Returns the new IJabberRosterItem that was created.

FindUserID(userid: string): IJabberRosterItem

This allows you to search the internal roster for a specific JID or a UserID. IE, you can send something like FindUserID('foo@jabber.com') as well as FindUserID('jabber:foo@jabber.com') The method returns either 'nil' if the item was not found or the actual IJabberRosterItem.

FindNick(nick: string): IJabberRosterItem

Returns either 'nil' or the RosterItem object which matches with the nick-name passed.

Delete(index: integer)

Delete an item from the roster

Clear

Clears the entire Roster.

Fetch

Get the current roster from the server and fill the internal contents with IJabberRosterItem objects.

---

IJabberRosterItem

This interface contains the details for a specific item in the roster. Note that all presence and resource information has been removed from Roster Items. All of this information is available by using the IJabberSession.GetPres method and using the resulting IJabberPres objects.

Properties

• NickName [string] - the nickname given to this roster item.
• JID [string] - The fully qualified JID for this user. This is normally something like: 'user@server.com/user-resource1' Note that the JID may not ALWAYS include the resource.
• UserID [string] - Just the userid portion of the JID, ie, 'user@server.com' from the above example.
• GroupCount [int] - how many groups is this user in?
• Group[index: int] - get a specific group.
• Subscription [JabberSubscriptionType] - The current subscription type.. to indicate to|from|both|none, etc..
• Ask [string] - the current 'ask' state for this roster item. Would indicate if a subscribe request is pending or not.
• Available [bool] - Is the person online or not?
• Status [string] - Current status flag ("Lunch", "working", etc..)
• Roster [IJabberRoster] - The Roster Interface which this item belongs to.

Methods

AddGroup(NewGrp: string)

Add a group to the roster item

DelGroup(DelGrp: string)

Remove a group from the list.

ClearGroups

Clear all the groups this user belongs to.

InGroup(Grp: string): bool

Does this user belong to a specific group or not?

Update

Send the current roster information back to the server so it gets stored permanently there.

---

IJabberMsg

This Interface encapsulates all of the message properties.

Properties

• FromJID [string] - where did the msg come from?
• ToJID [string] - where is the msg going?
• Subject [string]
• Thread [string]
• Body [string] - The COM object will handle escaping special characters. Just pass the text you want to send.
• MsgType [JabberMsgType] - jmtNormal | jmtChat | jmtGroupChat
• MsgTag [IXMLTag] - Returns the xml tag from the properties.

Methods

AddXTag: IXMLTag

This creates a new x tag inside the XML and returns the interface to the new tag. Use this interface passed back to change attributes, and add child nodes to the x tag.

ClearXTags

This method will remove all of the x tags contained in the message's XMLTag.

---

IJabberIQ

This interface contains an entire 'iq' and 'query' tag and has a series of IXMLFields. These fields are basic xml tags which contain a "field-name" and "field-data". These objects are very useful when dealing with basic "database-type" storage on the server.

Properties

• Namespace [String] - the namespace for this xml tag.
• iqType [String] - The 'type' attribute from the iq tag. Typically either 'set', 'get' or 'result'.
• ToJID [String] - Where to send the resulting xml.
• FromJID [String] - Where did the iq tag come from?
• ID [String] - The 'id' attribute from the iq tag.
• Fields [IXMLIterator] - Returns an Iterator for all of the fields.
• ReqFields [IXMLIterator] - Returns an Iterator interface for JUST the required fields.
• XML [String] - Returns the xml for this JabberIQ object.

Methods

ReadField(FieldName: string) [string]

Returns the string data for the associated field name.

SetField(FieldName: string; FieldData: string)

Set the field data for this field. By setting the data to a empty string, the field will NOT be included in the resulting XML when sent using the SEND method. If the field does not already exist, then create a new field.

---

IJabberAgents

This interface contains the list of Agents for a specific parent object. The parent object could be a IJabberSession, or a IJabberAgentItem. This interface works very similar to the IJabberRoster interface.

Properties

• Count [int] - How many AgentItems are in this list?
• Items [index: int] - Returns a specific AgentItem interface for the corresponding index.
• Session [IJabberSession] - a pointer to the session which owns this object.
• JID - a pointer to the JID of this agents list.

Methods

Fetch(iqID: string)

Fetches the list of agents from the server. This should populate the Items property. This will kick off the corresponding IJabberSession events. Pass the desired ID to use in the xml (which will also be used for the result), or leave it blank to have the COM Lib assign an ID for you.

Add(IXMLTag): IJabberAgentItem

This method builds a new AgentItem object based on the XMLTag that was passed in. It returns an interface to the new object.

FindAgent(Name: String): IJabberAgentItem

Search the list for a specific Agent Name and returns an interface to it's JabberAgentItem object.

FindJID(jid: String): IJabberAgentItem

Searchs the list for a specific Agent JID and returns an interface to it's JabberAgentItem object.

Clear

Clear and free all the contain AgentItem objects.

---

IJabberAgentItem

This interface contains details and info about a specific Agent on the server. Each agent may contain several properties. These are very similar to the JabberIQ stuff.

Properties

• JID [String] - The JID of this agent.
• Name [String] - The name of this agent.
• Properties [IXMLIterator] - Returns an iterator interface to the properties. Not that the elements contained in this list will be XMLFields.
• Parent [IJabberAgents] - A pointer to the agent list that owns this agent item.
• Agents [IJabberAgents] - A list of all the sub-agents for this agent.
• Key [String] - the key used during registration queries.

Methods

GetProp(Value: string): string

This returns a string containing the contents of this property.

SetProp(Key, value: string)

Either add or set a new property value for a specific key.

GetRegister(ID: String)

This sends an iq type='get' xml tag to the server. This will force an new JabberIQ to be created. Send a specific ID into this function so you can catch the corresponding JabberIQ when it comes through the JabberSession.OnJabberIQ event.

SetRegister(ID: string; SetIQ: IJabberIQ)

This sends an iq type='set' xml tag to the server containing all of the properties. Use this to send a completed or modified registration query. Use the ID to specify an ID to be used. Use this ID to catch the OnJabberIQ when it comes back. You should pass in a complete JabberIQ with the fields set appropriately. The method will automatically assign the from/to JIDs, and the correct namespace.

DeleteRegister(ID: String)

This method will remove the account/registration information from the server.

---

IJabberPres

This interface describes a single presence tag. These objects are returned from the IJabberSession.GetPres method (see above) and can be used to get current online/offline status, "show" information, as well as resource information.

Properties

• JID [String] - The JID of this user (no resource)
• Resource [String] - Resource for this presence
• Status [String] - The "long" descriptive status for this presnece.
• Priority [Integer] - The priority for this presence (0 or higher).
• ShowType [JabberShowType] - A "Show" style to tell other clients your current status. Can be: jshowNone (Default), jshowChat, jshowAway, jshowNA, jshowDND.