added migrated 2.x add-ons

Signed-off-by: Kai Kreuzer <kai@openhab.org>

bundles/org.openhab.binding.mail/README.md

@@ -0,0 +1,129 @@
+# Mail Binding
+
+The Mail binding provides support for sending mails from rules.
+
+## Supported Things
+
+There are three things: `smtp`, `imap` and `pop3` which represents respective servers.
+
+## Thing Configuration
+
+### SMTP Server (`smtp`)
+
+There are two mandatory parameters `hostname` and `sender`.
+
+The `hostname` may contain an IP address or a FQDN like `smtp.gmail.com`.
+The `sender` must be a valid mail address used as sender address for mails.
+
+The `security`, `port`, `username` and `password` parameters are optional.
+
+The `security` parameter defines the transport security and can be set to `PLAIN` (default), `STARTTLS` or `SSL` (for implicit SSL/TLS).
+The `port` parameter is used to change the default ports for the SMTP server.
+Default ports are `25` (for `PLAIN` and `STARTTLS`) and `465` (for `SSL`).
+For authentication, `username` and `password` can be supplied.
+If one or both are empty, no authentication data is provided to the SMTP server during connect.
+
+### IMAP Server (`imap`) / POP3 Server (`pop3`)
+
+There is one mandatory parameter: `hostname`, `username`, `password`.
+The `hostname` may contain an IP address or a FQDN like `mail.gmail.com`.
+For authentication `username` and `password` need to be supplied.
+
+The `refresh`, `security`, `port`, `username` and `password` parameters are optional.
+
+The `refresh` parameter is the time in seconds between two refreshes of the thing's channels.
+If omitted, the default of 60s is used.
+The `security` parameter defines the transport security and can be set to `PLAIN` (default), `STARTTLS` or `SSL` (for implicit SSL/TLS).
+The `port` parameter is used to change the default ports for the SMTP server.
+Default ports are `143` (for `PLAIN` and `STARTTLS`) and `993` (for `SSL`) in the case of `imap` or `110` (for `PLAIN` and `STARTTLS`) and `995` (for `SSL`) in the case of `pop3`.
+
+## Channels
+
+There are no channels for the `smtp` thing.
+The `imap` and `pop3` things can be extended with `mailcount`-type channels.
+
+### Type `mailcount`
+
+Each channel has two parameters: `folder` and `type`.
+The `folder` is mandatory and denotes the folder name on the given account.
+You can either use the root folder like (e.g. "INBOX") or a sub directory of your structure (e.g. "INBOX.Sent" or "INBOX.Junk").
+The `type` parameter can be `UNREAD` or `TOTAL` (default).
+Channels with type `UNREAD` give the number on unread mails in that folder.
+
+## Full Example
+
+mail.things:
+
+```
+Thing mail:smtp:samplesmtp [ hostname="smtp.example.com", sender="mail@example.com", security="SSL", username="user", password="pass" ]
+
+Thing mail:imap:sampleimap [ hostname="imap.example.com", security="SSL", username="user", password="pass" ] {
+    Channels:
+        Type mailcount : inbox_total [ folder="INBOX", type="TOTAL" ]
+        Type mailcount : inbox_unread [ folder="INBOX", type="UNREAD" ]
+}
+```
+
+mail.items:
+
+```
+Number InboxTotal  "INBOX [%d]"        { channel="mail:imap:sampleimap:inbox_total" }
+Number InboxUnread "INBOX Unread [%d]" { channel="mail:imap:sampleimap:inbox_unread" }
+```
+
+mail.sitemap:
+
+```
+sitemap demo label="Main Menu"
+{
+    Frame {
+        Text item=InboxTotal
+        Text item=InboxUnread
+    }
+}
+```
+
+## Rule Action
+
+This binding includes rule actions for sending email.
+Six different actions available:
+
+* `boolean success = sendMail(String recipient, String subject, String text)`
+* `boolean success = sendMail(String recipient, String subject, String text, String URL)`
+* `boolean success = sendMail(String recipient, String subject, String text, List<String> URL)`
+* `boolean success = sendHtmlMail(String recipient, String subject, String htmlContent)`
+* `boolean success = sendHtmlMail(String recipient, String subject, String htmlContent, String URL)`
+* `boolean success = sendHtmlMail(String recipient, String subject, String htmlContent, List<String> URL)`
+
+The `sendMail(...)` send a plain text mail (with attachments if supplied).
+The `sendHtmlMail(...)` send a HTML mail (with attachments if supplied).
+
+Both functions return a boolean as the result of the operation.
+
+`recipient` can be a single address (`mail@example.com`) or a list of addresses, concatenated by a comma (`mail@example.com, mail2@example.com`).
+
+Since there is a separate rule action instance for each `smtp` thing, this needs to be retrieved through `getActions(scope, thingUID)`.
+The first parameter always has to be `mail` and the second is the full Thing UID of the SMTP server that should be used.
+Once this action instance is retrieved, you can invoke the action method on it.
+
+Please note: All strings are expected to be UTF-8 encoded.
+Using different character sets may produce unwanted results.
+
+Examples:
+
+```
+val mailActions = getActions("mail","mail:smtp:samplesmtp")
+val success = mailActions.sendMail("mail@example.com", "Test subject", "This is the mail content.")
+success = mailActions.sendMail("mail1@example.com, mail2@example.com", "Test subject", "This is the mail content sent to multiple recipients.")
+
+```
+
+```
+import java.util.List
+
+val List<String> attachmentUrlList = newArrayList(
+  "http://some.web/site/snap.jpg&param=value",
+  "file:///tmp/201601011031.jpg")
+val mailActions = getActions("mail","mail:smtp:sampleserver")
+mailActions.sendHtmlMail("mail@example.com", "Test subject", "<h1>Header</h1>This is the mail content.", attachmentUrlList)
+```