This chapter provides an overview of MMS (short for Multimedia Messaging Service) and the Mbuni MMS Gateway.
MMS offers mobile users enhanced messaging capabilities like the ability to send pictures and sound from a cell phone. It is generally considered the natural successor to the very popular SMS service.
MMS usage has continued to grow since introduction, and it is expected that projects such as Mbuni should further boost the adoption of MMS and its explosion.
The Mbuni Project attempts to provide that little bit of boost to MMS adoption/growth, by providing two important parts of the MMS infrastructure: For the network "operator" Mbuni includes a fully-fledged MMS switching centre (MMSC), while for the MMS content provider Mbuni includes a MMS Value Added Services (VAS) Gateway (MMSBox).
Mbuni implements all major MMS interfaces, including phone-to-phone (so-called MM1 interface), phone-to-email (MM3), inter-MMSC (MM4) and MMS VAS (MM7). The level of support for each type of interface is listed on status page of the website.
Mbuni is inspired, in part by the Kannel project, and utilises Kannel's GWLIB and WAP libraries. Kannel provides well-designed, simple interfaces for management of octet strings, lists, threads, servers, etc, and a certified WAP implementation. This made it a natural choice for Mbuni, rather than re-inventing the wheel.
The Multimedia Messaging Service (MMS), is intended to provide a rich set of content to subscribers (pictures, audio, games, etc). It supports both sending and receiving of rich content by properly enabled client devices. MMS is a non-real-time delivery service, much like SMS or email. The service utilises a store-and-forward usage model.
MMS is designed to be transported largely over IP rather than traditional GSM (SS7) networks. It is also designed to interoperate with other IP services such as email and WAP. In fact, MMS messages are typically transported over WAP, and are encoded using WAP MIME formats.
Multimedia messages can be originated by or terminate to end-user client devices (i.e. MMS-enabled phones) or third party applications (typically used by MMS content providers). In the MMS architecture, the MMSC acts as the message-switching system within the core network, while the MMSBox acts as the message dispatch and content management system on the VAS (third party) side. The overall architecture is shown below.
The elements shown in the figure can be summarised as follows:
Typically, the message cycle begins with a user sending a multimedia message (MM) from the MMS client. The client must be configured for MMS, which includes bearer settings (i.e. GPRS or GSM/CSD settings), WAP gateway address and MMS Gateway address (a URL). On receipt of the message, the MMSC decides how to deliver the message (e.g. to another MMS client or to a VASP), and proceeds to dispatch the message. A VASP may also originate a message to the MMSC, for onward delivery.
An MM is typically a multi-part message
with pictures, sound, text and other media. Each part of the message is
identified by media (MIME) type, name and/or Content ID. Usually the
message is of a multipart/related MIME type, with the start element
being a SMIL part that
controls how the message should be displayed.
When submitting a
message, the MMS client indicates the intended recipient list, but usually not
the sender address, which the MMSC retrieves from the WAP
gateway. Like Email, a single MMS can specify
multiple recipients (MSISDNs and Email addresses), and it is up to the MMSC
to ensure correct delivery to each of the recipients.
When the MMSC receives a message destined for an email address, it typically re-codes the message as standard MIME and passes it on to an SMTP server for delivery. Email messages received are similarly re-coded as MMS and forwarded to the relevant MMS Client.
When the MMSC receives a message destined to MMS Clients in the area served by the MMSC, the message is stored and an MMS notification sent to the recipient via WAP Push. On receipt of the notification, the client typically fetches the message via a URL provided in the notification.
When a recipient requests an incoming MM from the server, it indicates to the server its capabilities for a User Agent Profile URL. The profile data includes such things as supported media types, screen size, supported character sets, etc. Typically, the MMSC will re-code the MM to suit the client's capabilities before returning the message. Messages destined to email may also be re-coded to make them more suitable for email readers.
The MMSC may also interface with a subscriber database, which controls message delivery and billing. The subscriber database will provide such information as which subscribers are provisioned for MMS, tariffs, etc.
On the VASP side of things, typically the content provider receives a request MM from a subscriber and must respond with an MM. The content to be sent back depends on the contents of the request.
Mbuni MMS gateway is a modular software system, designed to be full-featured, efficient and simple, supporting current generation multimedia messaging. Mbuni operates in one of two modes: As an MMSC or as a VAS gateway.
The Gateway is designed and tested to conform to Open Mobile Alliance (OMA), WAP and 3rd Generation Partnership Project (3GPP) MMS standards including:
Mbuni is being developed on MacOS X and Linux systems using the C programming language. It should compile and run on any similar system.
Mbuni utilises some libraries that are part of the Kannel source, specifically GWLIB and WAP libraries. In order to install Mbuni you will need to install (a patched) Kannel (and therefore fulfil those dependencies Mbuni shares with it).
The following additional components are required:This section explains the steps required to install the gateway. If you are installing from a binary distribution, you may safely skip to here.
In brief, to install Mbuni, you need to:
The source code for Mbuni is available for download from the download area of the website
In order to compile the software, you will first need to download and install Kannel v1.4.1 from kannel.org:
Unpack the kannel source files using a command like:
bzip2 -cd gateway-1.4.1.tar.bz2 | tar xf -
Then proceed to compile and install Kannel normally:
./configure
make install
Download and unzip/tar Mbuni sources in a directory of your choice:
tar xzf mbuni-version.tgzWhere version is the verion of Mbuni (e.g. 1.0.0). Compile and install mbuni as follows:
cd
mbuni-version
./bootstrap
./configure
make insall
If you installed Kannel in a non-standard location, you will need to supply the location to configure using --with-kannel=kannel_directory
If you want to try out the development version of Mbuni, you can download it from the CVS on sourceforge.net:
cvs -d:pserver:anonymous@mbuni.cvs.sourceforge.net:/cvsroot/mbuni loginMbuni consists of 4 programs:
mmsrelay is the main relay server of the MMSC. It routes
incoming messages to email, other MMS gateways, MMS clients/handsets,
etc. It also manages routing messages to MMS clients
using WAP Push, sending of delivery reports, etc.
mmsproxy
provides the HTTP interface of the MMSC via which messages are
sent and received by MMS clients.
mmsfromemail is
the email2MMS MMSC module.
mmsbox is the VAS gateway
If you intend to use Mbuni as an MMSC, be sure to install all other required components as detailed above, otherwise parts of the MMS gateway may not function correctly.
Mbuni expects that an AMR decoder is installed and can be invoked
as:
amrdecoder infile outfile
to decode an AMR
file to header-less (raw), 16-bit signed, mono, 8kHz audio samples in
the output file. (Input and output files may be '-' for standard input
or output respectively.)
Similarly, it is expected that an AMR encoder
called amrencoder exists and can be executed as follows:
amrencoder mode infile outfile
and convert raw, 16-bit signed, 8kHz
mono audio samples in the input file to AMR using the supplied
encoding mode.
For the AMR encoder/decoder, we have adapted the sample provided on the 3GPP
website. Follow the instructions below to install it:
To run the MMSC, you must run (mmsrelay and mmsproxy). mmsfromemail should be called from your MTA (SMTP Mailer) to convert and deliver an MMS from an email sender. The order in which they are started is unimportant.
To run Mbuni as a VAS gateway you must run mmsbox
All Mbuni programs expect the configuration file to be passed as the last argument on the command line (default is mbuni.conf). The configuration file controls most aspects of the operation of the gateway.
The configuration file format is the same as that used
by Kannel. The configuration file consists of groups of configuration
variables. Groups are separated by empty lines, each variable is defined on its
own line. Each group begins with the group name. Comments are lines that begin
with a hash (#) and are ignored.
A
variable definition line has the name of the variable, an equals sign (=) and
the value of the variable. The name of the variable can contain any characters
except white space and equals. The value of the variable is a string, with or
without quotation marks (") around it. Quotation marks are needed if the value
begins or ends with white space or contains special characters. Normal C escape
character syntax works inside quotation marks.
The variable group marks the beginning of a new group with the given name.
The core group is
core and defines the log file location, log level (amount of debugging
information – the lower the number the more debugging
information), the location of the access log, the HTTP proxy
host/port if any (HTTP proxy host/port
is specified using the exact same parameters as used by Kannel.) and
SSL client and server certificate files to be used for incoming and
outgoing HTTPS connections, if Kannel and Mbuni are compiled to have
SSL enabled. The syntax for specifying SSL certificates is exactly as
that used by Kannel.
group =
core
log-file
= log/mmsgw.log
log-level
= 0
access-log = log/access.log
This should be followed by the main gateway configuration group (mbuni).
group =
mbuni
name =
"My MMSC"
hostname
= ds.co.ug
host-alias
= mmsc
local-prefixes
= 075;+25675;25675
directory-store
= spool
max-send-threads
= 5
send-mail-prog
= /usr/sbin/sendmail -f %f %t
...
The table below lists all the configuration directives. The column Mode indicates operation mode in which the parameter is applicable: Config params marked VAS GW are only applicable when operating in VAS Gateway mode, while those marked MMSC are only applicable when operating in MMSC mode. The rest are used in both modes.
| Variable Name | Mode | Type | Description |
| group | ALL | mbuni | Mandatory variable |
| name | ALL | string | User-friendly name for the Gateway, used in notices, etc |
| hostname | MMSC | string | Local hostname. This is added as a qualifier to the sender address when MMS is forwarded to Email or to a foreign MMSC via SMTP. Defaults to localhost |
| host-alias | MMSC | string | Short MMC hostname. This is used in generating message IDs as well as the message retrieval URL (sent as part of the MMS notification): For instance if you have this as mmsc then the retrieval URL will have the form http://mmsc/msgtoken (no port is added). Be sure to keep this value short (as some handsets do not like long URLs in MMS notifications), and it must not include non-alphanumeric characters as this can screw up URL location parsing. If you do not supply a host alias, the gateway will create a long form URL (http://hostname:port/msgtoken) when it sends notifications |
| local-prefixes | MMSC | Number prefix list | Number prefixes that should be considered local. Messages to numbers that match these prefixes will be delivered locally (via mmsrelay) |
| storage-directory | ALL | Directory name (string) | Directory where Mbuni creates message queues, MMBoxes, and the User Agent profiles cache. Mbuni creates a set of sub-directories in here for each function |
| max-send-threads | ALL | Number | How many queue processing threads to start. A higher value means messages get delivered faster. |
| send-mail-prog | MMSC | String | Command to use for sending email messages (MMS-to-email or to foreign MMS gateways via SMTP). This command can include variables: %f – replaced with the message from address, %t – replaced with the recipient address (RFC 822 compliant), %s – the message subject, %m – the message ID. (NOTE: Special shell characters — &, |, $, (, ), and so on &mdash are escaped after variable substitution, hence parameter quoting is not necessary.) |
| unified-prefix | ALL | Number list | A string to unify received phone numbers, so that routing works correctly. Format is that first comes the unified prefix, then all prefixes which are replaced by the unified prefix, separated with comma (','). For example "+256,000256,0;+,000" should ensure correct UG prefixes. If there are several unified prefixes, separate their rules with semicolon (';') |
| maximum-send-attempts | ALL | integer | Maximum number of attempts gateway must make to deliver message before giving up (e.g. mobile phone is off, VAS service is down, email domain is unavailable) |
| default-message-expiry | ALL | Integer | Default number of seconds in which message expires and is purged from queue (if not yet delivered). This figure is overridden by whatever is in the message. |
| queue-run-interval | ALL | Real | How many seconds between each queue run |
| send-attempt-back-off | ALL | Integer | The exponential back-off factor to employ on subsequent message delivery attempts, when a delivery attempt fails. |
| sendsms-url | MMSC | String | URL of the service through which SMS can be sent to a mobile subscriber (e.g. for WAP Push). It is expected that this url expects/supports Kannel-style send-sms parameters (udh, from, to, text, etc.) |
| sendsms-username | MMSC | String | Username to pass (for authentication) to send-sms URL |
| sendsms-password | MMSC | String | Password to pass (for authentication) to send-sms URL |
| sendsms-global-sender | MMSC | String | Optional sender (to field) to use in send sms url |
| mms-port | MMSC | Integer | Port on which mmsproxy listens for MMS messages from MMS clients (Default is 8191). |
| mm7-port | MMSC | Integer | Port on which mmsproxy listens for MM7 requests from Value Added Services providers. If this port is not supplied, the MM7 sub-system is not started. |
| allow-ip | ALL | List of IP addresses | List of IP addresses of hosts allowed to use/access the Send MMS Port (MM1 interface for MMSC or SendMMS port for VAS Gateway). You can use this for instance to insist that only connections coming via a known/trusted WAP gateway are serviced by the MMSC. Leave out to allow all machines to connect. |
| deny-ip | ALL | List of IP addresses | List of IP addresses of hosts not allowed to use/access the Send MMS Port (MM1 interface for MMSC or SendMMS port for VAS Gateway). |
| mms-client-msisdn-header | MMSC | String | Name of HTTP Header sent/inserted by WAP gateway as part of MMS request to indicate MSISDN of sender. Note that typically the MMS client does not indicate its MSISDN in the MMS message, it is up to the gateway to discover this and insert it. We rely on the WAP gateway to provide the MSISDN as an HTTP request header (default header name is X-WAP-Network-Client-MSISDN) |
| mms-client-ip-header | MMSC | String | Name of HTTP Header sent/inserted by WAP gateway as part of MMS request to indicate IP Address of sender. Similar to the above, if the MSISDN is not set, then we assume that the client is identified by IP address, which we extract from the request headers (using this header). Default header name is X-WAP-Network-Client-IP. If the header is not found, we assume the IP address as seen by Mbuni's MM1 interface. |
| allow-ip-type | MMSC | Boolean | Set this to false to prevent Mbuni accepting and processing messages from senders identified by IP address (i.e. not by MSISDN). Default: True. |
| optimize-notification-size | MMSC | Boolean | Set this to true make Mbuni attempt to squeeze MMS notifications in one WAP Push SMS, by leaving out subject and sender fields. Default: false |
| content-adaptation | MMSC | Boolean | Set this to false to turn off content adaptation in Mbuni. This will cause the MMSC to ignore client capabilities when sending messages, and could cause problems so beware! Default: true |
| email2mms-relay-hosts | MMSC | Number list | A semi-colon separated list of hosts/domains. When MMS is received via SMTP, the gateway needs to determine whether it is for a local or a foreign recipient. To determine if the recipient is local recipient, we use the resolver module, if supplied. (Note that default resolution uses local-prefixes setting to determine if the recipient is local, returning the local MMSC name, if not, then it checks each of the defined relays to see if the recipient address is for one of them, by checking the prefixes, returning the matching proxy/relay name.) The resolver should return a host name that is matched against this setting. If any name matches, the message is queued, otherwise it is discarded. |
| billing-library | MMSC | String | Optional library containing billing and CDR functions. This library is loaded at runtime and should contain functions to be called to effect billing and CDR generation. See mms_billing.h for details. |
| billing-module-parameters | MMSC | String | Parameters to pass to the billing module specified above when it is loaded. This is a generic string whose interpretation is entirely up to the module. |
| resolver-library | MMSC | String | Optional library containing functions for resolving recipient MSISDN to hostname of Proxy-Relay that should handle the message. Supplying this libary over-rides the local-prefixes setting given above. If the Proxy-Relay hostname returned by the module is the hostname of the local MMSC, then the recipient is considered local. See mms_resolve.h for details. |
| resolver-module-parameters | MMSC | String | Parameters to pass to the Resolver module specified above when it is loaded. This is a generic string whose interpretation is entirely up to the module. |
| detokenizer-library | String | MMSC | Optional library containing functions for finding MSISDN from request URL sent by client. The last part of URL is treated as a string that is interpreted by the library and transformed into an MSISDN. This libary is only a fall-back in case the default sender address resolution fails. See mms_detokenize.h for details. |
| detokenizer-module-parameters | MMSC | String | Parameters to pass to the De-tokenizer module specified above when it is loaded. This is a generic string whose interpretation is entirely up to the module. |
| prov-server-notify-script | MMSC | String | Subscriber database interface script 1: This script will be called by the gateway to notify the subscriber database of per-subscriber events such as when a subscriber sends a message, successfully fetches a message, etc. This script is called with 4 arguments. Argument 1 is one of fetched, sent, failedfetch; argument 2 is the subscriber MSISDN; argument 3, in case of a failed fetch provides a description of the error (e.g. message expired); argument 4 is the message ID (if any). NOTE: Any missing argument is passed as a quoted empty string for ease of parsing in the script. |
| prov-server-sub-status-script | MMSC | string | Subscriber database interface script 2: This script is called by mmsrelay to determine whether the recipient's device supports MMS. The script should exit with a value of 0 to indicate that the device does not support receipt of MMS notifications; 1 to indicate that the device supports MMS; -1 if the subscriber is not known or not provisioned for MMS. The return value determines how mmsrelay will deliver the message (see below). |
| notify-unprovisioned | MMSC | Boolean | Whether subscribers who are not provisioned for MMS should receive any notifications (e.g. SMS) when an MMS message is received for them. |
| mms-notify-text | String | MMSC | Message to send to device that does not support MMS, when a message is received for the user. This message is sent as plain SMS via the Send SMS URL specified above. |
| mms-notify-unprovisioned-text | MMSC | String | Message to send to devices that are not provisioned for MMS (only if notify-unprovisioned is true). |
| mms-message-too-large-txt | MMSC | String | If a device tries to fetch a message, which during content adaptation is determined to be too large for the target device (based on capabilities data supplied by the device), the message is discarded, this text is sent to the device instead as part of an MMS message. |
| mms-to-email-html | MMSC | string | When an MM is destined for email, we must format it to make it more suitable for email readers. (For instance, the SMIL part of the MM will make no sense to most email readers.) The gateway formats the message as follows: It generates a multi-part MIME message with the main part being an HTML entity in which MM parts are embedded. The text given here is tagged at the bottom of the HTML. |
| mms-to-email-txt | MMSC | String | This string is placed in the MMS converted to email as an alternative to the HTML part, for email clients that do not support HTML. |
| mms-to-email-default-subject | MMSC | String | This string is used as the default message subject when sending MMS to email in the event that no subject is defined in the message |
| sendmms-port | VAS GW | number | The port on which the MMS VAS gateway listens for incoming MMS send requests. (Optional.) |
| sendmms-port-ssl | VAS GW | Boolean | Set to true if SendMMS port of VAS Gateway should be secure (HTTPS). This is only supported if Mbuni is compiled with SSL support. |
MMS Value-Added Service Providers (VASPs) are configured using one or more mms-vasp groups:
| Variable | Type | Description |
| group | String | Mandatory: mms-vasp |
| vasp-id | String | User friendly name |
| type | String | This should be one of: soap, eaif |
| short-code | Number | Short number for this VASP: Messages received by Mbuni to this number are routed to the VASP via MM7. |
| vasp-url | String | Outgoing messages to the VASP are sent via this URL (using HTTP POST) |
| vasp-username | String | Incoming HTTP authentication: The username used by the VASP to authenticate itself to Mbuni when sending data |
| vasp-password | String | Incoming HTTP authentication: The password used by the VASP to authenticate itself to Mbuni when sending data to the VASP |
| mms-to-email-handler | Boolean | Set this to true if all MMS destined to email addresses should be routed via this VASP by the MMC. The message will be packed as an MM7 message and handed over. This could be used to customise the appearance of the email. |
| mms-to-local-copy-handler | Boolean | Set this to true if all MMS destined to local recipients (e.g. mobiles) should be copied to this VASP. This is useful if you want to implement a web-based viewer (as a backup solution) for your users. |
Foreign MMS Gateways are configured using one or more mmsproxy groups:
| Variable | Type | Description |
| group | String | Mandatory: mmsproxy |
| name | String | User friendly name |
| host | String | Fully qualified domain name |
| allowed-prefix | Number list | List of recipient number prefixes that can be delivered via this Proxy |
| denied-prefix | Number list | List of recipient number prefixes that cannot be delivered via this proxy |
When an MM destined to an MSISDN cannot be delivered locally, the gateway searches the list of Proxies to see if one of them can handle the message. If one is found, the message is formatted as MIME and sent via SMTP to the proxy.
When Mbuni is used as a VAS Gateway, the configurations in this section are required to ensure smooth functioning of the system. We describe each configuration set in turn.
MMSC connections are configured using one or more mmsc groups:
group = mmsc| Variable | Type | Description |
| group | String | Mandatory: mmsc |
| id | String | Mandatory: Identifying name for this connection (used in logs for instance). For MM7 connections it also used as the VASP ID parameter |
| type | String | Mandatory: Protocol spoken by this MMSC, one of soap (for 3GPP MM7 SOAP) or eaif for Nokia EAIF protocol. |
| mmsc-url | String | Mandatory: URL address for the MMSC. Used for outgoing messages |
| incoming-port | Number | Port at which Mbuni listens for incoming messages from MMSC |
| incoming-user | string | Username to be used by MMSC to authenticate itself to Mbuni for incoming connections. (Using HTTP basic authentication scheme.) |
| incoming-password | string | Password to be used by MMSC to authenticate itself to Mbuni for incoming connections |
| incoming-port-ssl | Boolean | Specifies whether incoming port is secure (i.e. incoming requests use secure HTTP). Only supported if Mbuni is compiled with SSL support. |
| allow-ip | List of IP addresses | List of IP addresses of hosts allowed to use/access the incoming MMS port |
| deny-ip | List of IP addresses | List of IP addresses of hosts not allowed to use/access the incoming MMS port |
| allowed-prefix | Number list | List of recipient number prefixes that can be delivered via this MMSC (used for routing out-going messages) |
| denied-prefix | Number list | List of recipient number prefixes that cannot be delivered via this MMSC |
| max-throughput | Number | Maximum number of messages per second (outgoing) that this MMSC can handle. |
To be able to send MMS into Mbuni via the sendMMS port (if configured), at least one sendmms user must be configured:
group = send-mms-userConfiguration parameters are:
| Variable | Type | Description |
| group | mandatory | send-mms-user |
| username | mandatory | Username |
| password | mandatory | Password |
| faked-sender | string | Optional sender address used (irrespective of whether from address has been specified in MMS send request). |
| deliver-report-url | string | Optional URL to call to send message delivery status as reported to the VAS gateway by a MMSC for a message submitted by this user. |
| read-report-url | string | Optional URL to call to send message read status reports as returned to the VAS gateway by a MMSC for a message submitted by this user. |
The Send MMS service can be invoked using HTTP GET or POST (both x-www-form-urlencoded and multipart/form-data) requests to the Send MMS port on the VAS Gateway hosts. The interface expects and processes the following CGI paramerters:
| CGI Variable | Description |
| username | authentication username (must match a configured send-mms-user). |
| password | authentication password (must match password of corresponding send-mms-user). |
| from | Message sender. This is over-ridden by faked-sender setting of the send-mms-user. |
| to | Message recipient(s). Multiple recipients can be separated with a whitespace. |
| subject | Message subject |
| mmsc | Outgoing MMSC via which to route the message. If this is not given, the VAS Gateway routes the message based on the recipient address and the allowed-prefix/denied-prefix settings for the configured MMSCs. Note: The VAS Gateway considers that any MMSC can handle email and IP address recipient addresses and so routes messages to such destinations to the first configured MMSC |
| dlr-url | URL to invoke when a delivery report for this message is received |
| rr-url | URL to invoke when a read report for this message is received |
| text | If provided, this is used as the (text) content of the MM to be sent. The content type of the MM is set to text/plain |
| charset | Used in conjuction with the text parameter, it specifies the character set of the text, if it is not the default (iso-8859-1). |
| smil | If provided, specifies the SMIL for the MM. An MM is built out of the SMIL as described below, and the MM body will have content type multipart/related, which is the expected default. |
| content | If provided, specifies the arbitrary content for the MM. The Content type of the content is determined either by the content_type CGI variable (see below), or if enctype=multipart/form-data is used in the HTTP POST request, then the content type associated with this variable data is used. |
| content_type | If the content variable is provided, this variable specifies the content type of the content. The default, if no content type is provided is application/octet-stream. |
| base-url | If the smil URL parameter is provided, then this parameter may be supplied to be used as the base URL for resolving all relative URLs specified within the SMIL file while building the MM. Default: http://localhost/ |
| vasid | This will be passed on the MMC as the VASID parameter in the MM7/SOAP message. If not provided, defaults to sendmms-user |
| servicecode | This will be passed on the MMC as the ServiceCode parameter in the MM7/SOAP message. If not provided, this parameter is not sent. |
Note: You should specify only one of text, smil or content, as only one of them makes sense at any time. specifying more than one causes others to be ignored.
If a delivery-report-url or read-report-url is specified for the send mms user (or as parameters in the send mms request), and a report is sent to the VAS Gateway by a MMSC, the relevant URL is called (using the HTTP GET method), and information about the report sent to it via X-Mbuni headers.
The SendMMS interface can also be used to send binary content (e.g. binary-coded MMS, image or audio) directly to Mbuni. This is done as follows:
Messages are routed to services based on the first word of the text part of the MM. That is, Mbuni extracts the first text part of the MM, and finds the first word — the keyword — in the message. Mbuni then searches through the list of configured MMS Services for a matching service based on the keyword, and fetches the response from the associated URL, file or program.
A sample service configuration might look like this:
group = mms-service
name = me
post-url = http://localhost/photoblog.php
catch-all = true
http-post-parameters = fx=true&images[]=%i&text[]=%t
accept-x-mbuni-headers = true
keyword = test
A detailed list of configuration parameters for MMS Services is given below.
| Variable | Type | Description |
| group | mandatory | mms-service |
| name | string | Service name. Used for logging, also sent to MMSC as VAS ID parameter for MM7 SOAP requests |
| keyword | string | mandatory keyword. Incoming messages whose text part matching this parameter will be routed via this service. |
| aliases | list of string | semi-colon separated list of keyword aliases. Any of these keywords will also match and cause message to be routed via the service. |
| catch-all | boolean | Set this to true if this is the default service (i.e. all other messages routed through this service in case of no match). |
| accepted-mmscs | list of strings | semi-colon separated list of MMSCs (listed by ID). Only messages from these MMSCs will be routed to this service on match. Leave this empty to allow all. |
| denied-mmscs | list of strings | Messages from these MMSCs will never be routed to this service on match. Leave this empty to allow all. |
| get-url | string | The URL to fetch for response content. No parameter substitution is done, but X-Mbuni headers are sent as part of the HTTP request. See below for an explanation on how the response content is interpreted. |
| exec | string | Program to execute to obtain response content. Response is exptected on standard output, and must be of type SMIL. See below for an explanation on how the SMIL is processed. |
| file | string | File from which to obtain response content. Response type is inferred from the file name extension for a few well-known media types (text, SMIL, GIF, JPEG, PNG, BMP/WBMP, WAV, AMR, MP3, etc.), otherwise it defaults to application/octet-stream. See below for further information on how fetched content is converted to an MM. |
| text | string | If provided, the response content is the value of this parameter, and is assumed to be of media type text/plain. |
| post-url | string | Response content is obtained as result of sending a HTTP POST request to the provided URL. The POST message is always submitted using the multipart/form-data encoding (such as that used by a web browser when an HTML form has the enctype=multipart/form-data parameter set). If http-post-parameters field is given (see below), then the relevant parameters are sent as part of the request. X-Mbuni headers are sent as well. See below for an explanation on how the response content is interpreted. |
| http-post-parameters | string | Used in conjunction with post-url. Parameters are provided in the same way as would be provided in an HTTP GET request (e.g. message=true&myname=test&image=%i). Parameter values that begin with % are interpolated according to the rules listed below. |
| accept-x-mbuni-headers | boolean | Set this to true if Mbuni should honour X-Mbuni HTTP headers in the service response. See below for the list of headers. |
| pass-thro-headers | List | Set this to a comma-separated list of HTTP response headers that, if received from the service response, should be passed to the MMC (with their corresponding values) unchanged. Note that these headers are merged with other headers generated by Mbuni. |
| omit-empty | boolean | Set this to true if Mbuni should send an empty response to the requestor if one is returned by the service |
| suppress-reply | boolean | Set this to true if Mbuni not send a reply back to the user of this service. Note that the request URL will still be invoked. |
| assume-plain-text | boolean | Set this to true if an unknown content type in the response should be mapped to plain text. |
| faked-sender | string | If set, Mbuni will change the sender address in the response message to this value, irrespective of any X-Mbuni headers or the original recipient address. |
| service-code | string | If set, Mbuni will use this as the ServiceCode parameter to send back the MMSC (MM7/SOAP only) in a SubmitReq packet. This paramter overrides the X-Mbuni-ServiceCode header, if set int the response. |
When the MMS Service response content is fetched by the VAS
gateway, it is converted into an MM based on the reported or
inferred (in the case of file content) response content
type. For content fetched from URLs, the content type is taken as
received from the HTTP server. For file content it is
inferred from the file extension. For exec content, it is
assumed to be SMIL.
General conversion rules are as follows:
Mbuni VAS Gateway utilises a number of HTTP extension headers to
pass additional MM information to and receive information from the
MMS Service. Note that all applicable headers are always sent in
the HTTP request, but headers are only honoured in the response if
the accept-x-mbuni-headers parameter of the service is set
to true. On the response side, if honoured, the set values
over-ride the ones in the request, and are used in the response.
The list of supported headers is listed below:
| Header | Description |
| X-Mbuni-From | MM Sender address (e.g. +25674334444/TYPE=PLMN) |
| X-Mbuni-Subject | MM Subject |
| X-Mbuni-To | Recipient address. Multiple recipients can be specified as separate headers or as a comma-separated value |
| X-Mbuni-Expiry | MM Expiry as an HTTP date. |
| X-Mbuni-DLR-Url | Delivery report URL. This URL will be called with the delivery report status. It is also sent X-Mbuni headers |
| X-Mbuni-RR-Url | Read Report URL. This URL is called with the read report status. It is sent X-Mbuni headers. |
| X-Mbuni-MMSC | MMSC (id) through which message was received (on the request side) or through which it should be routed. |
| X-Mbuni-Message-ID | MM message ID. Only makes sense on the request side. |
| X-Mbuni-Report-Type | One of delivery-report or read-report, used when calling the DLR or RR URL. |
| X-Mbuni-MM-Status | Report status. Used in conjuction with X-Mbuni-Report-Type for transmitting report status. |
| X-Mbuni-ServiceCode | ServiceCode parameter for MM7/SOAP response packet. If set, its value is sent to the MMSC as the value of the ServiceCode element in the MM7/SOAP message body. |
When a post-url is used, you may specify the GCI parameters
to be sent in the POST transaction, using % escaepe codes as
interpolation markers. The list of supported escape codes is listed
below:
| Escape Code | Description |
| %i | Image part(s) of the MM |
| %v | Video part(s) of the MM |
| %t | Text part(s) of the MM |
| %s | SMIL part(s) of the MM |
| %a | Audio part(s) of the MM |
| %b | Entire, binary coded MM |
| %z | All part(s) of the MM |
| %o | Other part(s) of the MM (not text, video, audio, smil, or audio) |
| %% | Interpolated as %. |
In this section we provide an overview of the gateway architecture.
This component (mmsproxy) is the main point of interaction between the gateway and MMS clients and VASPs. It provides an HTTP interface through which clients can send MMS messages. From clients, message types expected on this interface are typically:
Currently, no MMbox quotas are imposed.
From VASPs mmsproxy expects and processes:The Relay watches the global queue for incoming messages (from VASP, external MMSCs or clients). For each message that arrives in the queue, the relay:
For messages placed in the mobile/local queue (i.e. those destined to MSISDNs in the area served by this MMSC or IP-based clients), the relay performs the following functions:
A word about queue management: A simple queue management scheme is
used. Each queue entry consists of two files: The 'q' file (which is
plain text) contains the entry control data
(list of recipients, next delivery attempt time, etc), the 'd' file
contains the message data. This scheme is similar to that used by
popular MTAs. Queue processors mostly operate on the 'q' file, and
use file locking to guard against duplicate delivery, file corruption,
etc.
See mms_queue.h for details.
The VAS gateway consists of a single multi-threaded program mmsbox. This program performs a number of simultaneous functions, including receiving incoming MM from MMSCs, dispatching requests to services, composing and sending responses, and listening for and handling sendmms requests. The key modules of the engine are described below.
The VAS gateway maintains two main message queues: One for incoming
messages (received from MMSCs), one for outgoing messages (received
from services or the send-mms port). These are maintained in
the storage-directory directory, in
directories mmsbox_incoming and mmsbox_outgoing
respectively. Queue structure is the same as that used by the MMSC component.
A separate directory (mmsbox_dlr) is maintained for storing DLR URLs.
We provide a sample Kannel wapbox config below, with some explanation
group = wapbox
bearerbox-host = localhost
log-file = "/tmp/wapbox.log"
syslog-level = none
access-log = "/tmp/wapaccess.log"
timer-freq = 10
map-url = "http://mmsc/* http://localhost:1981/*"
This is a live example that was used in tests. In the example we use: