modules/smsframework/API.txt

$Id: API.txt,v 1.4 2008/08/20 19:52:52 diggersf Exp $

h1. Overview

The SMS Framework API allows your modules to take advantage of the convenience
and flexibility of SMS messaging. In most cases your module will fall into one
of two categories.

* Modules that provide integration between the framework and Drupal. Your
  module could provide a feature that could integrate nicely with SMS or your
  module could supplement an existing module with SMS integration.

* Modules that provide integration between the framework and a third party SMS
  service.

Different parts of the API are used for each of these applications, so it's
important to decide which you'll be building using before you begin.

h1. Writing a Gateway Module

The first step is to tell the SMS Framework about your gateway module using
hook_gateway_info(). Your implementation of this hook should return and array of
properties and callbacks about each gateway. Here is an example:

  function my_gateway_gateway_info() {
    return array(
      'my_gateway' => array(
        'name' => 'My Gateway',
        'send' => 'my_gateway_send',
        'receive' => TRUE,
        'configure form' => 'my_gateway_admin_form',
        'send form' => 'my_gateway_send_form',
      ),
    );
  }
    
* name - Human readable name for the gateway.
* send - Callback function that the SMS Framework will call to send a message
* receive (optional) - Set to true if the gateway has support for handling
  incoming messages
* configure form (optional) - Form function for gateway configuration options
* send form (optional) - Form function for adding gateway-specific fields to
  the sending form
  
h3. Create the custom send function

Next you need to write the callback function for sending SMS messages using
your gateway. Using the example from above, our function would look something
like this:

  function my_gateway_send($number, $message, $options) {
    // Code for sending message through third party gateway service
    return $result;
  }

The callback function is passed the following parameters:
$number - The validated destination number.
$message - The text of the message.
$options (optional) - An array of additional properties as defined your gateway
module's send form.

The callback should return an array indicating the result of the send. Here is
an example:

  $result = array(
    'status' => FALSE,
    'message' => 'Could not connect to %server.',
    'variables' => array('%server', 'http://www.example.com'),
  );
  return $result;
  
* status - Set to TRUE if the send was successful, FALSE if it was not.
* message - If 'status' is FALSE, you may provide more details about the error.
  See t() for documentation on how 'message' and 'variables' interact. Keep
  'message' translatable by not concatenating dynamic values into it!
* variables - Array of variables to replace in the message or NULL
  if message is already translated or not possible to translate.

The actual contents of the function will depend on the gateway service. Refer
to the gateway's API documentation.

h3. Define gateway-specific fields for send forms

The SMS Framework allows gateway modules to specify custom fields to
be added to what's called the "send form." SMS enabled modules use this form 
in most cases to collect mobile information from the end-user. It is generated
by calling sms_send_form() and your gateway module can add custom fields
specifying a callback function for the 'send form' property in
hook_gateway_info(). Here's an example:

  function my_gateway_send_form($required = FALSE) {
    // Define custom fields here. Values from each field will be made available
    // in the options parameter of your gateway's sending callback.
    return $form;
  }

h3. Handle incoming messages with sms_incoming()

If the gateway you are integrating with has support for two-way messaging, you
may use sms_incoming() to pass incoming messages into the SMS Framework. Your
gateway module will be the first point of contact for messages coming in from
the gateway. Gateway services pass incoming messages to applications in
different ways (HTTP GET/POST, SOAP, XML-RPC, etc). Refer to the API
documentation for your gateway service.

After receiving the message and doing any necessary pre-processing, your module
should call sms_incoming(). Here is an example:

  function my_gateway_incoming_callback() {
    // Any necessary processing to extract the number and message
    sms_incoming($number, $message);
  }

h2. Writing a SMS Enabled Module

# @todo How to use sms_send()
# @todo How to use hook_sms_send()
1	$Id: API.txt,v 1.4 2008/08/20 19:52:52 diggersf Exp $
2
3	h1. Overview
4
5	The SMS Framework API allows your modules to take advantage of the convenience
6	and flexibility of SMS messaging. In most cases your module will fall into one
7	of two categories.
8
9	* Modules that provide integration between the framework and Drupal. Your
10	module could provide a feature that could integrate nicely with SMS or your
11	module could supplement an existing module with SMS integration.
12
13	* Modules that provide integration between the framework and a third party SMS
14	service.
15
16	Different parts of the API are used for each of these applications, so it's
17	important to decide which you'll be building using before you begin.
18
19	h1. Writing a Gateway Module
20
21	The first step is to tell the SMS Framework about your gateway module using
22	hook_gateway_info(). Your implementation of this hook should return and array of
23	properties and callbacks about each gateway. Here is an example:
24
25	function my_gateway_gateway_info() {
26	return array(
27	'my_gateway' => array(
28	'name' => 'My Gateway',
29	'send' => 'my_gateway_send',
30	'receive' => TRUE,
31	'configure form' => 'my_gateway_admin_form',
32	'send form' => 'my_gateway_send_form',
33	),
34	);
35	}
36
37	* name - Human readable name for the gateway.
38	* send - Callback function that the SMS Framework will call to send a message
39	* receive (optional) - Set to true if the gateway has support for handling
40	incoming messages
41	* configure form (optional) - Form function for gateway configuration options
42	* send form (optional) - Form function for adding gateway-specific fields to
43	the sending form
44
45	h3. Create the custom send function
46
47	Next you need to write the callback function for sending SMS messages using
48	your gateway. Using the example from above, our function would look something
49	like this:
50
51	function my_gateway_send($number, $message, $options) {
52	// Code for sending message through third party gateway service
53	return $result;
54	}
55
56	The callback function is passed the following parameters:
57	$number - The validated destination number.
58	$message - The text of the message.
59	$options (optional) - An array of additional properties as defined your gateway
60	module's send form.
61
62	The callback should return an array indicating the result of the send. Here is
63	an example:
64
65	$result = array(
66	'status' => FALSE,
67	'message' => 'Could not connect to %server.',
68	'variables' => array('%server', 'http://www.example.com'),
69	);
70	return $result;
71
72	* status - Set to TRUE if the send was successful, FALSE if it was not.
73	* message - If 'status' is FALSE, you may provide more details about the error.
74	See t() for documentation on how 'message' and 'variables' interact. Keep
75	'message' translatable by not concatenating dynamic values into it!
76	* variables - Array of variables to replace in the message or NULL
77	if message is already translated or not possible to translate.
78
79	The actual contents of the function will depend on the gateway service. Refer
80	to the gateway's API documentation.
81
82	h3. Define gateway-specific fields for send forms
83
84	The SMS Framework allows gateway modules to specify custom fields to
85	be added to what's called the "send form." SMS enabled modules use this form
86	in most cases to collect mobile information from the end-user. It is generated
87	by calling sms_send_form() and your gateway module can add custom fields
88	specifying a callback function for the 'send form' property in
89	hook_gateway_info(). Here's an example:
90
91	function my_gateway_send_form($required = FALSE) {
92	// Define custom fields here. Values from each field will be made available
93	// in the options parameter of your gateway's sending callback.
94	return $form;
95	}
96
97	h3. Handle incoming messages with sms_incoming()
98
99	If the gateway you are integrating with has support for two-way messaging, you
100	may use sms_incoming() to pass incoming messages into the SMS Framework. Your
101	gateway module will be the first point of contact for messages coming in from
102	the gateway. Gateway services pass incoming messages to applications in
103	different ways (HTTP GET/POST, SOAP, XML-RPC, etc). Refer to the API
104	documentation for your gateway service.
105
106	After receiving the message and doing any necessary pre-processing, your module
107	should call sms_incoming(). Here is an example:
108
109	function my_gateway_incoming_callback() {
110	// Any necessary processing to extract the number and message
111	sms_incoming($number, $message);
112	}
113
114	h2. Writing a SMS Enabled Module
115
116	# @todo How to use sms_send()
117	# @todo How to use hook_sms_send()