Create README.md

2015-05-24 22:39:49 +01:00
parent 5b1efdfeab
commit 326a5512ab
1 changed files with 92 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,92 @@
+# Stabber
+Stubbed XMPP (Jabber) Server.
+# Overview
+Stabber acts as a stubbed XMPP service for testing purposes, with an API to allow:
+* Sending of XMPP stanzas.
+* Responding to XMPP stanzas with stubbed responses.
+* Verifying that XMPP stanzas were received.
+
+The project is work in progress with only the basics implemented, and is being developed alongside boothj5/profanity
+Currently the only API is written in C.
+# Installing
+```
+./bootstrap.sh
+./configure
+make
+make install (as root)
+```
+# Using in a project
+Include the following header in your tests:
+```
+#include <stabber.h>
+````
+Include the following in the linker path when compiling tests:
+```
+-lstabber
+```
+# API
+### Starting
+To start Stabber on port 5230 for example:
+```c
+stbbr_start(5230);
+```
+### Stopping
+To stop Stabber:
+```c
+stbbr_stop();
+```
+### Authentication
+Currently only legacy authentication is supported, to set the password that stabber expects when an account connects:
+```c
+stbbr_auth_passwd("mypassword");
+```
+The default if not set is "password".
+### Sending stanzas
+To make Stabber send an XMPP stanza:
+```c
+stbbr_send(
+    "<iq id=\"ping1\" type=\"get\" to=\"stabber@localhost/profanity\" from=\"localhost\">"
+        "<ping xmlns=\"urn:xmpp:ping\"/>"
+    "</iq>"
+);
+```
+### Responding to stanzas
+As well as being able to send an XMPP stanza at any time, you can also response to a stanza by its id attribute:
+```c
+stbbr_for("msg_21",
+    "<message id=\"message17\" to=\"stabber@localhost\" from=\"buddy1@localhost/mobile\" type=\"chat\">"
+        "<body>I'm not real!</body>"
+    "</message>"
+);
+```
+### Verify sent stanzas
+To verify that you send a particular stanza to Stabber:
+```c
+stbbr_verify(
+    "<message id=\"msg24415\" to=\"buddy1@localhost/mobile\" type=\"chat\">"
+        "<body>I know, its a test.</body>"
+    "</message>"
+);
+```
+The above function returns 1 id the stanza has been received, and 0 if it hasn't.
+The following function check that it was specifically the last stanza received:
+```c
+stbbr_verify_last(
+    "<message id=\"msg24415\" to=\"buddy1@localhost/mobile\" type=\"chat\">"
+        "<body>I know, its a test.</body>"
+    "</message>"
+);
+```
+Both verifications allow for wildcards (*) as attribute values, for example, if you don't know the id's that are generated by your client:
+```c
+stbbr_verify(
+    "<message id=\"*\" to=\"buddy1@localhost/mobile\" type=\"chat\">"
+        "<body>I know, its a test.</body>"
+    "</message>"
+);
+````
+# Logs
+Stabber logs to:
+```
+~/.local/share/stabber/logs/stabber.log
+```