Merge pull request #6 from PeterNerlich/contacts

Contacts

api.lua

@@ -14,43 +14,86 @@ all 4 parameters (old compat version)
 see: "Mail format" api.md
 --]]
 function mail.send(src, dst, subject, body)
+	-- figure out format
 	local m
 	if dst == nil and subject == nil and body == nil then
 		-- new format (one object param)
 		m = src
 	else
 		-- old format
 		m = {}
-		m.src = src
-		m.dst = dst
+		m.from = src
+		m.to = dst
 		m.subject = subject
 		m.body = body
 	end
 
+	local cc
+	local bcc
+	local extra
+	-- log mail send action
+	if m.cc or m.bcc then
+		if m.cc then
+			cc = "CC: " .. m.cc
+			if m.bcc then
+				cc = cc .. " - "
+			end
+		else
+			cc = ""
+		end
+		if m.bcc then
+			bcc = "BCC: " .. m.bcc
+		else
+			bcc = ""
+		end
+		extra = " (" .. cc .. bcc .. ")"
+	else
+		extra = ""
+	end
+	minetest.log("action", "[mail] '" .. m.from .. "' sends mail to '" .. m.to .. "'" ..
+		extra .. "' with subject '" .. m.subject .. "' and body: '" .. m.body .. "'")
 
-	minetest.log("action", "[mail] '" .. m.src .. "' sends mail to '" .. m.dst ..
-		"' with subject '" .. m.subject .. "' and body: '" .. m.body .. "'")
 
-	local messages = mail.getMessages(m.dst)
+	-- normalize to, cc and bcc while compiling a list of all recipients
+	local recipients = {}
+	m.to = mail.normalize_players_and_add_recipients(m.to, recipients)
+	if m.cc then
+		m.cc = mail.normalize_players_and_add_recipients(m.cc, recipients)
+	end
+	if m.bcc then
+		m.bcc = mail.normalize_players_and_add_recipients(m.bcc, recipients)
+	end
 
-	table.insert(messages, 1, {
+	-- form the actual mail
+	local msg = {
 		unread  = true,
-		sender  = m.src,
+		sender  = m.from,
+		to      = m.to,
 		subject = m.subject,
 		body    = m.body,
 		time    = os.time(),
-	})
-	mail.setMessages(m.dst, messages)
+	}
+	if m.cc then
+		msg.cc  = m.cc
+	end
+
+	-- send the mail to all recipients
+	for _, recipient in pairs(recipients) do
+		local messages = mail.getMessages(recipient)
+		table.insert(messages, 1, msg)
+		mail.setMessages(recipient, messages)
+	end
 
+	-- notify recipients that happen to be online
 	for _, player in ipairs(minetest.get_connected_players()) do
 		local name = player:get_player_name()
-		if name == m.dst then
+		if recipients[string.lower(name)] ~= nil then
 			if m.subject == "" then m.subject = "(No subject)" end
 			if string.len(m.subject) > 30 then
 				m.subject = string.sub(m.subject,1,27) .. "..."
 			end
-			minetest.chat_send_player(m.dst,
-					string.format(mail.receive_mail_message, m.src, m.subject))
+			minetest.chat_send_player(name,
+					string.format(mail.receive_mail_message, m.from, m.subject))
 		end
 	end
 

api.md

@@ -2,6 +2,25 @@
 # Mail format
 The mail format in the api hooks
 
+```lua
+mail = {
+	from = "sender name",
+	to = "players, which, are, addressed",
+	cc = "carbon copy",
+	bcc = "players, which, get, a, copy, but, are, not, visible, to, others",
+	subject = "subject line",
+	body = "mail body",
+	-- 8 attachments max
+	attachments = {"default:stone 99", "default:gold_ingot 99"}
+}
+```
+
+The fields `to`, `cc` and `bcc` can contain a player, multiple player names separated by commas, or be empty. Players in `to` are the recipiants, who are addressed directly. `cc` specifies players that get the mail to get notified, but are not immediate part of the conversation. There is no technical difference between `to` and `cc`, it just implies meaning for the players. Players can see all fields making up the mail except `bcc`, which is the only difference to `cc`.
+
+Attachments need to be provided for each player getting the mail. Until this is implemented, trying to send a mail to multiple players will fail.
+
+The `from` and `to` fields were renamed from the previous format:
+
 ```lua
 mail = {
 	src = "source name",
@@ -22,8 +41,10 @@ mail.send("source name", "destination name", "subject line", "mail body")
 New variant (1.1+)
 ```lua
 mail.send({
-	src = "source name",
-	dst = "destination name",
+	from = "sender name",
+	to = "destination name",
+	cc = "carbon copy",
+	bcc = "blind carbon copy",
 	subject = "subject line",
 	body = "mail body"
 })