modules/smsgateway/PROVIDER-README.txt

$Id: $

SMS Service Provider Interface
==============================

Introduction
------------
This document defines the interface between the main SMS Gateway module and the 
Service Provider plugins. There are 5 hook methods for the plugin to implement.
In all these example 'provider' is used in place of the name of the plugin 
module. 

Module Naming and Discovery
---------------------------
The provider plugin module should be named 'gateway_provider.inc' where 
'provider' is replaced by the name of the plugin as described above. This 
normally would be a combination of the company name of the gateway service 
provider followed by an underscore and the protocol used.

For example 'clickatell_http' for the HTTP Protocol implementation of the 
Clickatell Service API.

Plugin Name
-----------
This hook method is used to retrieve the human-readable name of the provider 
plugin, for use in selection user interface.

Hook Name: smsgateway_gateway_provider_name
Parameters: None.
Returns: String containing the human-readable name of service provider and 
  protocol.
  
Plugin Description
------------------
This hook method is used to retrieve the human-readable decription of the 
module, containing more information about where to go to get information about
the service provider and protocol, allowing a user to register an account with
the service provider.
 
Send Single Message
-------------------
This hook method sends a single message to the gateway provider.

Hook Name: smsgateway_gateway_provider_sendsingle
Parameters: 
  (1) smssettings - array of settings containing the account information to 
      allow message transmission. 
        'serverurl' The URL used to connect to the server.
        'account_id' The identifier of the account to use
        'accountname' The account or username used to login
        'password' The password to use to login
        'from' The telephone number to be used for the sender
        'usessl' 1 to indicate the use of an SSL connection
  (2) message - array of message specific variables
        'destination_number' the destination telephone number to send the 
	    message to
        'message_body' the text body of the message
Returns: an array of response variables.
        'response' the vendor specific text response as sent by the provider 
	    gateway server
        'connectstring' a debug string indicating the string used to connect to 
	    the server (if supported) 
        'initialbalance' the balance at the start of the send (if supported)

Send Single Message
-------------------
This hook method sends a batch of messages to the gateway provider.

Hook Name: smsgateway_gateway_provider_sendbatch
Parameters: 
  (1) smssettings - array of settings containing the account information to 
      allow message transmission. 
        'serverurl' The URL used to connect to the server.
        'account_id' The identifier of the account to use
        'accountname' The account or username used to login
        'password' The password to use to login
        'from' The telephone number to be used for the sender
        'usessl' 1 to indicate the use of an SSL connection
  (2) message - an array of messages keyed by a unique ID for the message. This 
      is used to track the responses for the individual messages. Each 
      individual message is itself an array of message specific variables:
        'destination_number' the destination telephone number to send the 
	    message to
        'message_body' the text body of the message
Returns: an array of response variables.
        'connectstring' a debug string indicating the string used to connect to 
	    the server (if supported) 
        'initialbalance' the balance at the start of the send (if supported)
        Id-specific - the Unique ID passed in with each message is used to track 
	    the vendor specific text response as sent by the provider gateway 
	    server

Parse Received Message
----------------------
This hook message parses a received message into a keyed array of variables. 
Currently the information is either from the URL get or post variables.
This function should ensure that all returned strings are HTML displayable 
by calling check_plain() on them.

Hook Name: smsgateway_gateway_provider_sendbatch
Parameters: None 
Returns: The received message as array of response variables keyed as follows:.
        'account_id' the ID of the account that the message was received on
        'sender_number' the telephone number of the message sender
        'destination_number' the telephone number that the message was sent to
        'timestamp' the timestamp placed on the message
        'charset' optional character set information for the message body
        'header' any additional header information
        'body' the body of the message - the message text

1	$Id: $
2
3	SMS Service Provider Interface
4	==============================
5
6	Introduction
7	------------
8	This document defines the interface between the main SMS Gateway module and the
9	Service Provider plugins. There are 5 hook methods for the plugin to implement.
10	In all these example 'provider' is used in place of the name of the plugin
11	module.
12
13	Module Naming and Discovery
14	---------------------------
15	The provider plugin module should be named 'gateway_provider.inc' where
16	'provider' is replaced by the name of the plugin as described above. This
17	normally would be a combination of the company name of the gateway service
18	provider followed by an underscore and the protocol used.
19
20	For example 'clickatell_http' for the HTTP Protocol implementation of the
21	Clickatell Service API.
22
23	Plugin Name
24	-----------
25	This hook method is used to retrieve the human-readable name of the provider
26	plugin, for use in selection user interface.
27
28	Hook Name: smsgateway_gateway_provider_name
29	Parameters: None.
30	Returns: String containing the human-readable name of service provider and
31	protocol.
32
33	Plugin Description
34	------------------
35	This hook method is used to retrieve the human-readable decription of the
36	module, containing more information about where to go to get information about
37	the service provider and protocol, allowing a user to register an account with
38	the service provider.
39
40	Send Single Message
41	-------------------
42	This hook method sends a single message to the gateway provider.
43
44	Hook Name: smsgateway_gateway_provider_sendsingle
45	Parameters:
46	(1) smssettings - array of settings containing the account information to
47	allow message transmission.
48	'serverurl' The URL used to connect to the server.
49	'account_id' The identifier of the account to use
50	'accountname' The account or username used to login
51	'password' The password to use to login
52	'from' The telephone number to be used for the sender
53	'usessl' 1 to indicate the use of an SSL connection
54	(2) message - array of message specific variables
55	'destination_number' the destination telephone number to send the
56	message to
57	'message_body' the text body of the message
58	Returns: an array of response variables.
59	'response' the vendor specific text response as sent by the provider
60	gateway server
61	'connectstring' a debug string indicating the string used to connect to
62	the server (if supported)
63	'initialbalance' the balance at the start of the send (if supported)
64
65	Send Single Message
66	-------------------
67	This hook method sends a batch of messages to the gateway provider.
68
69	Hook Name: smsgateway_gateway_provider_sendbatch
70	Parameters:
71	(1) smssettings - array of settings containing the account information to
72	allow message transmission.
73	'serverurl' The URL used to connect to the server.
74	'account_id' The identifier of the account to use
75	'accountname' The account or username used to login
76	'password' The password to use to login
77	'from' The telephone number to be used for the sender
78	'usessl' 1 to indicate the use of an SSL connection
79	(2) message - an array of messages keyed by a unique ID for the message. This
80	is used to track the responses for the individual messages. Each
81	individual message is itself an array of message specific variables:
82	'destination_number' the destination telephone number to send the
83	message to
84	'message_body' the text body of the message
85	Returns: an array of response variables.
86	'connectstring' a debug string indicating the string used to connect to
87	the server (if supported)
88	'initialbalance' the balance at the start of the send (if supported)
89	Id-specific - the Unique ID passed in with each message is used to track
90	the vendor specific text response as sent by the provider gateway
91	server
92
93	Parse Received Message
94	----------------------
95	This hook message parses a received message into a keyed array of variables.
96	Currently the information is either from the URL get or post variables.
97	This function should ensure that all returned strings are HTML displayable
98	by calling check_plain() on them.
99
100	Hook Name: smsgateway_gateway_provider_sendbatch
101	Parameters: None
102	Returns: The received message as array of response variables keyed as follows:.
103	'account_id' the ID of the account that the message was received on
104	'sender_number' the telephone number of the message sender
105	'destination_number' the telephone number that the message was sent to
106	'timestamp' the timestamp placed on the message
107	'charset' optional character set information for the message body
108	'header' any additional header information
109	'body' the body of the message - the message text
110