wimax-tools  1.4.4
internal.h
Go to the documentation of this file.
1 /*
2  * Linux WiMax
3  * Internal API and declarations
4  *
5  *
6  * Copyright (C) 2007-2008 Intel Corporation. All rights reserved.
7  * Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>
8  *
9  * Redistribution and use in source and binary forms, with or without
10  * modification, are permitted provided that the following conditions
11  * are met:
12  *
13  * * Redistributions of source code must retain the above copyright
14  * notice, this list of conditions and the following disclaimer.
15  * * Redistributions in binary form must reproduce the above copyright
16  * notice, this list of conditions and the following disclaimer in
17  * the documentation and/or other materials provided with the
18  * distribution.
19  * * Neither the name of Intel Corporation nor the names of its
20  * contributors may be used to endorse or promote products derived
21  * from this software without specific prior written permission.
22  *
23  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
24  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
25  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
26  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
27  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
28  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
29  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
30  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
31  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
32  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
33  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
34  *
35  *
36  */
37 #ifndef __lib_internal_h__
38 #define __lib_internal_h__
39 
40 #include <wimaxll.h>
41 
42 struct nl_msg;
43 struct nlmsgerr;
44 struct sockaddr_nl;
45 
46 enum {
47 #define __WIMAXLL_IFNAME_LEN 32
48  /**
49  * WIMAXLL_IFNAME_LEN - Maximum size of a wimax interface
50  * name.
51  */
53 };
54 
55 
56 /**
57  * General structure for storing callback context
58  *
59  * \ingroup callbacks
60  *
61  * Callbacks set by the user receive a user-set pointer to a context
62  * structure. The user can wrap this struct in a bigger context struct
63  * and use wimaxll_container_of() during the callback to obtain its
64  * pointer.
65  *
66  * Usage:
67  *
68  * \code
69  * ...
70  * struct wimaxll_handle *wmx;
71  * ...
72  * struct my_context {
73  * struct wimaxll_cb_ctx ctx;
74  * <my data>
75  * } my_ctx = {
76  * .ctx = WIMAXLL_CB_CTX_INIT(wmx),
77  * <my data initialization>
78  * };
79  * ...
80  * wimaxll_set_cb_SOMECALLBACK(wmx, my_callback, &my_ctx.ctx);
81  * ...
82  * result = wimaxll_pipe_read(wmx);
83  * ...
84  *
85  * // When my_callback() is called
86  * my_callback(wmx, ctx, ...)
87  * {
88  * struct my_context *my_ctx = wimaxll_container_of(
89  * ctx, struct my_callback, ctx);
90  * ...
91  * // do stuff with my_ctx
92  * }
93  * \endcode
94  *
95  * \param wmx WiMAX handle this context refers to (for usage by the
96  * callback).
97  * \param result Result of the handling of the message. For usage by
98  * the callback. Should not be set to -EINPROGRESS, as this will
99  * be interpreted by the message handler as no processing was done
100  * on the message.
101  *
102  * \internal
103  *
104  * \param msg_done This is used internally to mark when the acks (or
105  * errors) for a message have been received and the message
106  * receiving loop can be considered done.
107  */
110  ssize_t result;
111  unsigned msg_done:1; /* internal */
112 };
113 
114 
115 /**
116  * Initialize a definition of struct wimaxll_cb_ctx
117  *
118  * \param _wmx pointer to the WiMAX device handle this will be
119  * associated to
120  *
121  * Use as:
122  *
123  * \code
124  * struct wimaxll_handle *wmx;
125  * ...
126  * struct wimaxll_cb_ctx my_context = WIMAXLL_CB_CTX_INIT(wmx);
127  * \endcode
128  *
129  * \ingroup callbacks
130  */
131 #define WIMAXLL_CB_CTX_INIT(_wmx) { \
132  .wmx = (_wmx), \
133  .result = -EINPROGRESS, \
134 }
135 
136 
137 static inline // ugly workaround for doxygen
138 /**
139  * Initialize a struct wimaxll_cb_ctx
140  *
141  * \param ctx Pointer to the struct wimaxll_cb_ctx.
142  * \param wmx pointer to the WiMAX device handle this will be
143  * associated to
144  *
145  * Use as:
146  *
147  * \code
148  * struct wimaxll_handle *wmx;
149  * ...
150  * struct wimaxll_cb_ctx my_context;
151  * ...
152  * wimaxll_cb_ctx(&my_context, wmx);
153  * \endcode
154  *
155  * \ingroup callbacks
156  * \fn static void wimaxll_cb_ctx_init(struct wimaxll_cb_ctx *ctx, struct wimaxll_handle *wmx)
157  */
158 void wimaxll_cb_ctx_init(struct wimaxll_cb_ctx *ctx, struct wimaxll_handle *wmx)
159 {
160  ctx->wmx = wmx;
161  ctx->result = -EINPROGRESS;
162 }
163 
164 
165 static inline // ugly workaround for doxygen
166 /**
167  * Set the result value in a callback context
168  *
169  * \param ctx Context where to set -- if NULL, no action will be taken
170  * \param val value to set for \a result
171  *
172  * \ingroup callbacks
173  * \fn static void wimaxll_cb_maybe_set_result(struct wimaxll_cb_ctx *ctx, int val)
174  */
175 void wimaxll_cb_maybe_set_result(struct wimaxll_cb_ctx *ctx, int val)
176 {
177  if (ctx != NULL && ctx->result == -EINPROGRESS)
178  ctx->result = val;
179 }
180 
181 
182 /**
183  * A WiMax control pipe handle
184  *
185  * This type is opaque to the user
186  *
187  * \internal
188  *
189  * In order to simplify multithread support, we use to different \a
190  * libnl handles, one for sending to the kernel, one for receiving
191  * from the kernel (multicast group). This allows us to parallelize \c
192  * wimaxll_msg_write() and \c wimaxll_msg_read() at the same time in a
193  * multithreaded environment, for example.
194  *
195  * \param ifidx Interface Index (of the network interface); if 0, the
196  * interface name will be \c "any" and this means that this handle
197  * works for \e any WiMAX interface.
198  * \param gnl_family_id Generic Netlink Family ID assigned to the
199  * device; we maintain it here (for each interface) because we
200  * want to discover it every time we open. This solves the case of
201  * the WiMAX modules being reloaded (and the ID changing) while
202  * this library is running; this way it takes only a new open when
203  * the new device is discovered.
204  * \param mcg_id Id of the 'msg' multicast group
205  * \param name name of the wimax interface
206  * \param priv Private pointer set with wimaxll_priv_set() or other
207  * accessors. Use wimaxll_priv_get() to access it.
208  * \param nlh_tx handle for writing to the kernel.
209  * Internal note: You \b have \b to set the handlers for
210  * %NL_CB_VALID and nl_cb_err() callbacks, as each callsite will
211  * do it to suit their needs. See wimaxll_rfkill() for an
212  * example. Any other callback you are supposed to restore to what
213  * it was before.
214  * \param nlh_rx handle for reading from the kernel.
215  * \param nl_rx_cb Callbacks for the nlh_rx handle
216  *
217  * FIXME: add doc on callbacks
218  */
220  unsigned ifidx;
223  void *priv;
224 
225  struct nl_handle *nlh_tx;
226  struct nl_handle *nlh_rx;
227 
230 
233 };
234 
235 
236 /* Utilities */
238 int wimaxll_gnl_handle_msg_to_user(struct wimaxll_handle *, struct nl_msg *);
239 int wimaxll_gnl_handle_state_change(struct wimaxll_handle *, struct nl_msg *);
240 int wimaxll_gnl_error_cb(struct sockaddr_nl *, struct nlmsgerr *, void *);
241 int wimaxll_gnl_ack_cb(struct nl_msg *msg, void *_mch);
242 
243 /*
244  * wimaxll_family_id - Return the associated Generic Netlink family ID
245  *
246  * @wmx: WiMax interface for which to provide the ID.
247  */
248 static inline
249 int wimaxll_family_id(struct wimaxll_handle *wmx)
250 {
251  return wmx->gnl_family_id;
252 }
253 
254 
255 void wimaxll_msg(struct wimaxll_handle *, const char *fmt, ...)
256  __attribute__ ((format(printf, 2, 3)));
257 
258 /* Generic Netlink utilities */
259 
260 int nl_get_multicast_groups(struct nl_handle *, const char *,
261  void (*cb)(void *, const char *, int),
262  void *);
263 int genl_ctrl_get_version(struct nl_handle *, const char *);
264 
265 #endif /* #ifndef __lib_internal_h__ */
int genl_ctrl_get_version(struct nl_handle *nlh, const char *name)
Definition: genl.c:171
A WiMax control pipe handle.
Definition: internal.h:219
void * msg_to_user_priv
Definition: internal.h:229
wimaxll_msg_to_user_cb_f msg_to_user_cb
Definition: internal.h:228
int gnl_family_id
Definition: internal.h:221
int nl_get_multicast_groups(struct nl_handle *handle, const char *family, void(*cbf)(void *, const char *, int), void *priv)
Enumerates the list of available multicast groups for a family.
Definition: genl.c:118
void wimaxll_cb_ctx_init(struct wimaxll_cb_ctx *ctx, struct wimaxll_handle *wmx)
Initialize a struct wimaxll_cb_ctx.
Definition: internal.h:158
void wimaxll_msg(struct wimaxll_handle *, const char *fmt,...) __attribute__((format(printf
int wimaxll_gnl_error_cb(struct sockaddr_nl *, struct nlmsgerr *, void *)
Netlink callback to process netlink callback errors.
Definition: wimax.c:72
int wimaxll_gnl_handle_msg_to_user(struct wimaxll_handle *, struct nl_msg *)
Callback to process an WIMAX_GNL_OP_MSG_TO_USER from the kernel.
Definition: op-msg.c:156
General structure for storing callback context.
Definition: internal.h:108
void * state_change_priv
Definition: internal.h:232
struct nl_handle * nlh_tx
Definition: internal.h:225
int wimaxll_wait_for_ack(struct wimaxll_handle *)
Wait for a netlink ACK and pass on the result code it passed.
Definition: wimax.c:165
int wimaxll_gnl_ack_cb(struct nl_msg *msg, void *_mch)
Netlink callback to process an ack message and pass the &#39;error&#39; code.
Definition: wimax.c:105
#define __WIMAXLL_IFNAME_LEN
Definition: internal.h:47
int(* wimaxll_state_change_cb_f)(struct wimaxll_handle *, void *priv, enum wimax_st old_state, enum wimax_st new_state)
Callback for a state change notification from the WiMAX kernel stack.
Definition: wimaxll.h:305
struct nl_handle * nlh_rx
Definition: internal.h:226
char name[__WIMAXLL_IFNAME_LEN]
Definition: internal.h:222
unsigned ifidx
Definition: internal.h:220
struct wimaxll_handle * wmx
Definition: internal.h:109
wimaxll_state_change_cb_f state_change_cb
Definition: internal.h:231
WIMAXLL_IFNAME_LEN - Maximum size of a wimax interface name.
Definition: internal.h:52
int wimaxll_gnl_handle_state_change(struct wimaxll_handle *, struct nl_msg *)
Callback to process an WIMAX_GNL_RE_STATE_CHANGE from the kernel.
Definition: re-state-change.c:120
int(* wimaxll_msg_to_user_cb_f)(struct wimaxll_handle *wmx, void *priv, const char *pipe_name, const void *data, size_t size)
Callback for a message to user generic netlink message.
Definition: wimaxll.h:278
void wimaxll_cb_maybe_set_result(struct wimaxll_cb_ctx *ctx, int val)
Set the result value in a callback context.
Definition: internal.h:175
int mcg_id
Definition: internal.h:221
ssize_t result
Definition: internal.h:110
unsigned msg_done
Definition: internal.h:111
void * priv
Definition: internal.h:223