Skip to main content
aboutsummaryrefslogtreecommitdiffstats
blob: edf0a3266a1784cafaae327fca504cbc58c90dfd (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
/*******************************************************************************
 * Copyright (c) 2008, 2013 IBM Corp.
 *
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * and Eclipse Distribution License v1.0 which accompany this distribution. 
 *
 * The Eclipse Public License is available at 
 *    http://www.eclipse.org/legal/epl-v10.html
 * and the Eclipse Distribution License is available at 
 *   http://www.eclipse.org/org/documents/edl-v10.php.
 *
 * Contributors:
 *    Ian Craggs - initial API and implementation and/or initial documentation
 *******************************************************************************/


/**
 * 
 * 
 * Description : Generic platform (gp) API header file 
 * 
 *
 */




#ifndef _MQTTS_GP_API_H
#define _MQTTS_GP_API_H



/*************************************************************************
 * The following functions are called by the mqtts client and have to be 
 * implemented by the generic platform (gp):
 *   1. Timer related functions: 
 *        * gp_timer_new
 *        * gp_timer_start
 *        * gp_timer_stop
 *        * gp_timer_end
 *   2. Messages related functions:
 *        * gp_network_msg_send
 *        * gp_network_msg_broadcast
 *        * gp_byte_get
 *   3. Help/Utility functions (optional, need not be implemented)
 *        * gp_debug (e.g. to print debug info)
 * 
 * There is only one callback function from gp, namely:
 * 		gpcb_network_msg_received()
 *************************************************************************/


/**
 * request gp to create a new timer
 * 
 * Parameters:
 *          timeout_funccb      callback-function when time-out happens
 * Return: 
 *          id of timer created
 */
unsigned char gp_timer_new(void (*timeout_funccb)(void));


/**
 * request gp to start indicated timer with the indicated timer value in seconds
 *   Parameters:
 *          id      id of timer to be started
 *          msb		most significant byte of timer value (in seconds)
 *          lsb		least significant byte of timer value
 *   Return:
 * 			none
 */
void gp_timer_start(unsigned char id,
		            unsigned char msb,
		            unsigned char lsb);


/**
 * request gp to stop indicated timer
 * 
 * Parameters:
 *          id  id of timer to be stopped
 * 
 * Return:
 *          none
 * 
 */
void gp_timer_stop(unsigned char id);

/**
 * request gp to end indicated timer (id cannot be used anymore)
 * 
 * Parameters:  id    id of timer to be ended
 * 
 * Return: 
 *          none
 * 
 */
void gp_timer_end(unsigned char id);

/**
 * request gp to send a message
 * 
 * Parameters: 
 *          *msg    pointer to first byte to be sent
 *                  (message's length is in first byte to send!)
 *          *dest   pointer to destination address
 *          length  length of destination address
 * 
 * Return:
 * 			none
 * 
 */
void gp_network_msg_send(unsigned char *msg,
		                 unsigned char *dest,
		                 unsigned char length);

/**
 * request gp to broadcast a message
 *
 * Parameters:
 *          *msg        pointer to first byte to be broadcasted
 *          			(message's length is in first byte to send!)
 *          radius      broadcast radius (0 means all network broadcast)
 * 
 * Return:
 * 			none
 * 
 */    
void gp_network_msg_broadcast(unsigned char *msg, 
		                      unsigned char radius);


/**
 * get a byte from a message just received
 * only called within the handling of gpcb_network_msg_received()
 * 
 * Parameters:
 *          *msg    pointer to the mqtts message 
 *                  (as received in gpcb_network_msg_received())
 *          index   index of the byte to get
 *                  index=1 => mqtts msg length field!
 * 
 * Return: 
 *          requested byte
 * 
 */
unsigned char gp_byte_get(unsigned char *msg, unsigned char index);


/** 
 * Optional function: print/display e.g. debug information
 * 
 * Parameters:
 *           *s       pointer to string or array to be displayed
 *           length   length of string/array to be displayed
 * 
 * Return:   
 * 			none
 * 
 */
#if MQTTS_DEBUG
//void gp_debug(char *s, ...);
void gp_debug(unsigned char *s, unsigned char length);
#endif


/*************************************************************************
 * callback functions (implemented by mqtts, see mqtts-core.c) 
 *************************************************************************/

/**
 * indicate the reception of a mqtts message
 * to be called by gp to give the msg to mqtts client
 * 
 * Parameters:
 *          *msg    	pointer to message received
 *          *sender 	pointer to sender's address
 *          length     	length of sender's address
 * 
 * Return:
 * 
 * NOTE 1: use gp_byte_get(msg,i) to get msg's byte #i !
 * NOTE 2: mqtts length field is in msg[1], not in msg[0] !
 */
void gpcb_network_msg_received(
		unsigned char *msg,
		unsigned char *sender,
		unsigned char length);


#endif

Back to the top