/// <summary>
/// Attempts to initiate a data stream with the XMPP entity with the specified
/// JID.
/// </summary>
/// <param name="to">The JID of the XMPP entity to initiate a data-stream
/// with.</param>
/// <param name="mimeType">The MIME type of the data to be transferred across
/// the stream.</param>
/// <param name="profile">The 'Stream Initiation' profile to use.</param>
/// <param name="streamOptions">An enumerable collection of supported
/// stream methods which are advertised to the receiving XMPP
/// entity.</param>
/// <param name="data">An XML element containing any additional data the
/// specified 'Stream Initiation' profile may require.</param>
/// <returns>An initialized instance of the InitiationResult class containing
/// the negotiated stream-method and session identifier.</returns>
/// <exception cref="ArgumentNullException">The to parameter or the mimeType
/// parameter or the profile parameter or the streamOptions parameter
/// is null.</exception>
/// <exception cref="ArgumentException">The streamOptions enumerable contains
/// no elements, or the stream-initiation response received contained no
/// selection for the stream-method.</exception>
/// <exception cref="NotSupportedException">The XMPP entity with
/// the specified JID does not support the 'Stream Initiation' XMPP
/// extension.</exception>
/// <exception cref="XmppErrorException">The server or the receiving XMPP
/// entity returned an XMPP error code. Use the Error property of the
/// XmppErrorException to obtain the specific error condition.</exception>
/// <exception cref="XmppException">The server returned invalid data or another
/// unspecified XMPP error occurred.</exception>
public InitiationResult InitiateStream(Jid to, string mimeType, string profile,
IEnumerable <string> streamOptions, XmlElement data = null)
{
to.ThrowIfNull("to");
mimeType.ThrowIfNull("mimeType");
profile.ThrowIfNull("profile");
streamOptions.ThrowIfNull("streamOptions");
if (streamOptions.Count() == 0)
{
throw new ArgumentException("The streamOptions enumerable must " +
"include one or more stream-options.");
}
if (!ecapa.Supports(to, Extension.StreamInitiation))
{
throw new NotSupportedException("The XMPP entity does not support " +
"the 'Stream Initiation' extension.");
}
string sid = GenerateSessionId();
var si = CreateSiElement(sid, mimeType, profile, streamOptions, data);
// Perform the actual request.
Iq iq = im.IqRequest(IqType.Set, to, im.Jid, si);
if (iq.Type == IqType.Error)
{
throw Util.ExceptionFromError(iq, "Stream initiation failed.");
}
// Result must contain a 'feature' element.
var feat = iq.Data["si"]["feature"];
string selected = ParseStreamMethod(feat);
// Construct and return the initiation result.
return(new InitiationResult(sid, selected, iq.Data["si"]));
}
/// <summary>
/// Returns an enumerable collection of blocked contacts.
/// </summary>
/// <returns>An enumerable collection of JIDs which are on the client's
/// blocklist.</returns>
/// <exception cref="NotSupportedException">The XMPP entity with
/// the specified JID does not support the 'Blocking Command' XMPP
/// extension.</exception>
/// <exception cref="XmppErrorException">The server returned an XMPP error code.
/// Use the Error property of the XmppErrorException to obtain the specific
/// error condition.</exception>
/// <exception cref="XmppException">The server returned invalid data or another
/// unspecified XMPP error occurred.</exception>
public IEnumerable <Jid> GetBlocklist()
{
// Probe for server support.
if (!ecapa.Supports(im.Jid.Domain, Extension.BlockingCommand))
{
throw new NotSupportedException("The server does not support " +
"the 'Blocking Command' extension.");
}
Iq iq = im.IqRequest(IqType.Get, null, im.Jid,
Xml.Element("blocklist", "urn:xmpp:blocking"));
if (iq.Type == IqType.Error)
{
throw Util.ExceptionFromError(iq, "The blocklist could not be retrieved.");
}
ISet <Jid> set = new HashSet <Jid>();
var list = iq.Data["blocklist"];
if (list == null || list.NamespaceURI != "urn:xmpp:blocking")
{
throw new XmppException("Erroneous server response.");
}
foreach (XmlElement item in list.GetElementsByTagName("item"))
{
try {
string jid = item.GetAttribute("jid");
set.Add(jid);
} catch (FormatException e) {
throw new XmppException("Encountered an invalid JID.", e);
}
}
return(set);
}
/// <summary>
/// Queries the XMPP entity with the specified JID for its software
/// version.
/// </summary>
/// <param name="jid">The JID of the XMPP entity to query.</param>
/// <returns>An instance of the VersionInformation class containing the
/// entity's software version.</returns>
/// <exception cref="ArgumentNullException">The jid parameter is
/// null.</exception>
/// <exception cref="NotSupportedException">The XMPP entity with
/// the specified JID does not support the 'Software Version' XMPP
/// extension.</exception>
/// <exception cref="XmppErrorException">The server returned an XMPP error code.
/// Use the Error property of the XmppErrorException to obtain the specific
/// error condition.</exception>
/// <exception cref="XmppException">The server returned invalid data or another
/// unspecified XMPP error occurred.</exception>
public VersionInformation GetVersion(Jid jid)
{
jid.ThrowIfNull("jid");
if (!ecapa.Supports(jid, Extension.SoftwareVersion))
{
throw new NotSupportedException("The XMPP entity does not support the " +
"'Software Version' extension.");
}
Iq response = im.IqRequest(IqType.Get, jid, im.Jid,
Xml.Element("query", "jabber:iq:version"));
if (response.Type == IqType.Error)
{
throw Util.ExceptionFromError(response, "The version could not be retrieved.");
}
// Parse the response.
var query = response.Data["query"];
if (query == null || query.NamespaceURI != "jabber:iq:version")
{
throw new XmppException("Erroneous server response: " + response);
}
if (query["name"] == null || query["version"] == null)
{
throw new XmppException("Missing name or version element: " + response);
}
string os = query["os"] != null ? query["os"].InnerText : null;
return(new VersionInformation(query["name"].InnerText,
query["version"].InnerText, os));
}
/// <summary>
/// Retrieves the time of the XMPP entity with the specified JID.
/// </summary>
/// <param name="jid">The JID of the XMPP entity to retrieve the time
/// for.</param>
/// <returns>The time of the XMPP entity with the specified JID.</returns>
/// <exception cref="ArgumentNullException">The jid parameter
/// is null.</exception>
/// <exception cref="NotSupportedException">The XMPP entity with
/// the specified JID does not support the 'Entity Time' XMPP extension.</exception>
/// <exception cref="XmppErrorException">The server returned an XMPP error code.
/// Use the Error property of the XmppErrorException to obtain the specific
/// error condition.</exception>
/// <exception cref="XmppException">The server returned invalid data or another
/// unspecified XMPP error occurred.</exception>
public DateTime GetTime(Jid jid)
{
jid.ThrowIfNull("jid");
if (!ecapa.Supports(jid, Extension.EntityTime))
{
throw new NotSupportedException("The XMPP entity does not support " +
"the 'Entity Time' extension.");
}
Iq iq = im.IqRequest(IqType.Get, jid, im.Jid,
Xml.Element("time", "urn:xmpp:time"));
if (iq.Type == IqType.Error)
{
throw Util.ExceptionFromError(iq, "The time could not be retrieved.");
}
var time = iq.Data["time"];
if (time == null || time["tzo"] == null || time["utc"] == null)
{
throw new XmppException("Erroneous IQ response.");
}
string tzo = time["tzo"].InnerText;
string utc = time["utc"].InnerText;
// Try to parse utc into datetime, tzo into timespan.
try {
DateTime dt = DateTime.Parse(utc).ToUniversalTime();
TimeSpan sp = TimeSpan.Parse(tzo.TrimStart('+'));
return(dt.Add(sp));
} catch (FormatException e) {
throw new XmppException("Invalid tzo or utc value.", e);
}
}
/// <summary>
/// Opens an in-band bytestream with the XMPP entity with the specified JID.
/// </summary>
/// <param name="to">The JID of the XMPP entity to open an in-band bytestream
/// with.</param>
/// <param name="sessionId">The session id obtained during stream
/// initiation.</param>
/// <remarks>This method expects that stream initiation has been previously
/// performed.</remarks>
/// <exception cref="NotSupportedException">The XMPP entity with
/// the specified JID does not support the 'In-Band Bytestreams' XMPP
/// extension.</exception>
/// <exception cref="XmppErrorException">The server returned an XMPP error code.
/// Use the Error property of the XmppErrorException to obtain the specific
/// error condition.</exception>
void OpenStream(Jid to, string sessionId)
{
if (!ecapa.Supports(to, Extension.InBandBytestreams))
{
throw new NotSupportedException("The XMPP entity does not support the " +
"'In-Band Bytestreams' extension.");
}
// Send the 'open' request.
var open = Xml.Element("open", "http://jabber.org/protocol/ibb")
.Attr("block-size", blockSize.ToString())
.Attr("sid", sessionId)
.Attr("stanza", "iq");
Iq response = im.IqRequest(IqType.Set, to, im.Jid, open);
if (response.Type == IqType.Error)
{
throw Util.ExceptionFromError(response, "The in-band bytestream could " +
"not be opened.");
}
}
/// <summary>
/// Gets the attention of the XMPP user with the specified JID.
/// </summary>
/// <param name="jid">The JID of the user to grab the attention of.</param>
/// <param name="message">A message to sent along.</param>
/// <exception cref="ArgumentNullException">The jid parameter
/// is null.</exception>
/// <exception cref="NotSupportedException">The XMPP entity with
/// the specified JID does not support the 'Attention' XMPP
/// extension.</exception>
public void GetAttention(Jid jid, string message = null)
{
jid.ThrowIfNull("jid");
if (!ecapa.Supports(jid, Extension.Attention))
{
throw new NotSupportedException("The XMPP entity does not support the " +
"'Attention' extension.");
}
Im.Message m = new Im.Message(jid, message);
// Add the 'attention' element to the message.
m.Data.Child(Xml.Element("attention", "urn:xmpp:attention:0"));
im.SendMessage(m);
}
/// <summary>
/// Offers the XMPP user with the specified JID the file with the specified
/// name and, if accepted by the user, transfers the file using the supplied
/// stream.
/// </summary>
/// <param name="to">The JID of the XMPP user to offer the file to.</param>
/// <param name="stream">The stream to read the file-data from.</param>
/// <param name="name">The name of the file, as offered to the XMPP user
/// with the specified JID.</param>
/// <param name="size">The number of bytes to transfer.</param>
/// <param name="cb">A callback method invoked once the other site has
/// accepted or rejected the file-transfer request.</param>
/// <param name="description">A description of the file so the receiver can
/// better understand what is being sent.</param>
/// <exception cref="ArgumentNullException">The to parameter or the stream
/// parameter or the name parameter is null.</exception>
/// <exception cref="ArgumentOutOfRangeException">The value of the size
/// parameter is negative.</exception>
/// <exception cref="NotSupportedException">The XMPP entity with the
/// specified JID does not support the 'SI File Transfer' XMPP
/// extension.</exception>
/// <exception cref="XmppErrorException">The server or the XMPP entity
/// with the specified JID returned an XMPP error code. Use the Error
/// property of the XmppErrorException to obtain the specific error
/// condition.</exception>
/// <exception cref="XmppException">The server returned invalid data or
/// another unspecified XMPP error occurred.</exception>
public void InitiateFileTransfer(Jid to, Stream stream, string name, long size,
string description = null, Action <bool, FileTransfer> cb = null)
{
to.ThrowIfNull("to");
stream.ThrowIfNull("stream");
name.ThrowIfNull("name");
size.ThrowIfOutOfRange(0, Int64.MaxValue);
if (!ecapa.Supports(to, Extension.SIFileTransfer))
{
throw new NotSupportedException("The XMPP entity does not support the " +
"'SI File Transfer' extension.");
}
// Perform stream-initiation asynchronously so that the caller is not
// blocked until the other site has either accepted or rejected our offer.
InitiateStreamAsync(to, name, size, description, (result, iq) => {
OnInitiationResult(result, to, name, stream, size, description, cb);
});
}
/// <summary>
/// Pings the XMPP entity with the specified JID.
/// </summary>
/// <param name="jid">The JID of the XMPP entity to ping.</param>
/// <returns>The time it took to ping the XMPP entity with the specified
/// JID.</returns>
/// <exception cref="ArgumentNullException">The jid parameter
/// is null.</exception>
/// <exception cref="NotSupportedException">The XMPP entity with
/// the specified JID does not support the 'Ping' XMPP extension.</exception>
/// <exception cref="XmppErrorException">The server returned an XMPP error code.
/// Use the Error property of the XmppErrorException to obtain the specific
/// error condition.</exception>
/// <exception cref="XmppException">The server returned invalid data or another
/// unspecified XMPP error occurred.</exception>
public TimeSpan PingEntity(Jid jid)
{
jid.ThrowIfNull("jid");
if (!ecapa.Supports(jid, Extension.Ping))
{
throw new NotSupportedException("The XMPP entity does not support the " +
"'Ping' extension.");
}
DateTime start = DateTime.Now;
Iq iq = im.IqRequest(IqType.Get, jid, im.Jid,
Xml.Element("ping", "urn:xmpp:ping"));
if (iq.Type == IqType.Error)
{
throw Util.ExceptionFromError(iq, "Could not ping XMPP entity.");
}
return(DateTime.Now.Subtract(start));
}
/// <summary>
/// Retrieves the data-item with the specified CID from the XMPP entity
/// with the specified JID.
/// </summary>
/// <param name="cid">The CID of the binary data to retrieve.</param>
/// <param name="from">The JID of the XMPP entity to request the data
/// from.</param>
/// <param name="cache">true to store the requested item in the local
/// cache for future references.</param>
/// <returns>The data-item with the specified CID.</returns>
/// <exception cref="ArgumentNullException">The cid parameter or the from
/// parameter is null.</exception>
/// <exception cref="NotSupportedException">The XMPP entity with
/// the specified JID does not support the 'Bits of Binary' XMPP
/// extension.</exception>
/// <exception cref="XmppErrorException">The server returned an XMPP error code.
/// Use the Error property of the XmppErrorException to obtain the specific
/// error condition.</exception>
/// <exception cref="XmppException">The server returned invalid data or another
/// unspecified XMPP error occurred.</exception>
public BobData Get(string cid, Jid from, bool cache = true)
{
cid.ThrowIfNull("cid");
from.ThrowIfNull("from");
// If the data is already in the cache, return it.
if (this.cache.ContainsKey(cid))
{
return(this.cache[cid]);
}
if (!ecapa.Supports(from, Extension.BitsOfBinary))
{
throw new NotSupportedException("The XMPP entity does not support " +
"the 'Bits of Binary' extension.");
}
// Request the data.
Iq iq = im.IqRequest(IqType.Get, from, im.Jid,
Xml.Element("data", "urn:xmpp:bob").Attr("cid", cid));
if (iq.Type == IqType.Error)
{
throw Util.ExceptionFromError(iq, "The data-item with the specified " +
"CID could not be retrieved.");
}
var data = iq.Data["data"];
if (data == null || data.NamespaceURI != "urn:xmpp:bob")
{
throw new XmppException("Erroneous response.");
}
try {
// Parse the response 'data' element.
BobData b = BobData.Parse(data);
if (cache)
{
this.cache[cid] = b;
}
return(b);
} catch (ArgumentException e) {
throw new XmppException("The retrieved data-item could not be " +
"processed.", e);
}
}
