$Id: API.txt,v 1.1.2.5 2008-09-18 13:55:35 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()