include/asp-session.h

   1 /*
   2  * Copyright (c) 2016 Samsung Electronics Co., Ltd.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef __ASP_SESSION_H__
  18 #define __ASP_SESSION_H__
  19
  20 #include <glib.h>
  21
  22 #ifdef __cplusplus
  23 extern "C" {
  24 #endif
  25
  26 /*****************************************************************************
  27  * Macros and Typedefs
  28  *****************************************************************************/
  29
  30 typedef enum {
  31         ASP_SESSION_CONNECT_STATUS_NETWORK_ROLE_REJECTED,
  32         ASP_SESSION_CONNECT_STATUS_NO_MORE_CONNECTION,
  33         ASP_SESSION_CONNECT_STATUS_SESSION_REQUEST_SENT,
  34         ASP_SESSION_CONNECT_STATUS_SESSION_REQUEST_RECEIVED,
  35         ASP_SESSION_CONNECT_STATUS_SESSION_REQUEST_DEFFERED,
  36         ASP_SESSION_CONNECT_STATUS_SESSION_REQUEST_ACCEPTED,
  37         ASP_SESSION_CONNECT_STATUS_SESSION_REQUEST_FAILED,
  38         ASP_SESSION_CONNECT_STATUS_GROUP_FORMATION_STARTED,
  39         ASP_SESSION_CONNECT_STATUS_GROUP_FORMATION_COMPLETED,
  40         ASP_SESSION_CONNECT_STATUS_GROUP_FORMATION_FAILED,
  41 } asp_session_connect_status_e;
  42
  43 typedef enum {
  44         ASP_SESSION_STATE_ERROR,
  45         ASP_SESSION_STATE_CLOSED,
  46         ASP_SESSION_STATE_INITIATED,
  47         ASP_SESSION_STATE_REQUESTED,
  48         ASP_SESSION_STATE_OPEN
  49 } asp_session_status_e;
  50
  51 typedef enum {
  52         ASP_SESSION_CLOSED_STATE_NONE,
  53         ASP_SESSION_CLOSED_STATE_DISASSOCIATED,
  54         ASP_SESSION_CLOSED_STATE_LOCAL_CLOSE,
  55         ASP_SESSION_CLOSED_STATE_REMOTE_CLOSE,
  56         ASP_SESSION_CLOSED_STATE_SYSTEM_FAILURE,
  57         ASP_SESSION_CLOSED_STATE_NO_RESPONSE_FROM_REMOTE
  58 } asp_session_closed_state_e;
  59
  60 typedef enum {
  61         ASP_SESSION_PORT_STATUS_LOCAL_PORT_ALLOWED,
  62         ASP_SESSION_PORT_STATUS_LOCAL_PORT_BLOCKED,
  63         ASP_SESSION_PORT_STATUS_FAILURE,
  64         ASP_SESSION_PORT_STATUS_REMOTE_PORT_ALLOWED
  65 } asp_session_port_status_e;
  66
  67 typedef enum {
  68         ASP_SESSION_REMOVE_SESSION_REASON_UNKNOWN = 0x00,
  69         ASP_SESSION_REMOVE_SESSION_REASON_REJECTED_BY_USER = 0x01,
  70         ASP_SESSION_REMOVE_SESSION_REASON_ADVERTISED_SERVICE_NOT_AVAILABLE = 0x02,
  71         ASP_SESSION_REMOVE_SESSION_REASON_SYSTEM_FAILURE = 0x03
  72 } asp_remove_session_reason_e;
  73
  74 typedef void (*asp_session_session_request_cb) (gint32 error_code,
  75                 guint8 *session_mac, guint32 session_id, guint32 adv_id,
  76                 gchar *device_name, size_t name_length, guint8 *session_info,
  77                 size_t info_length, gboolean get_pin, guint32 pin, gpointer user_data);
  78                 /*if pin is zero, it does not need to be displayed. */
  79
  80 typedef void (*asp_session_session_config_request_cb) (gint32 error_code,
  81                 guint8 *session_mac, guint32 session_id, gboolean get_pin, guint32 pin,
  82                 gpointer user_data);
  83
  84 typedef void (*asp_session_connect_status_cb) (gint32 error_code,
  85                 const guint8 *session_mac, guint32 session_id,
  86                 asp_session_connect_status_e status, guint8 *deferred_resp,
  87                 size_t resp_length, gpointer user_data);
  88
  89 typedef void (*asp_session_session_status_cb) (gint32 error_code,
  90                 const guint8 *session_mac, guint32 session_id,
  91                 asp_session_status_e state, asp_session_closed_state_e status,
  92                 const gchar *requested_info, gpointer user_data);
  93
  94 typedef void (*asp_session_port_status_cb) (gint32 error_code,
  95                 const guint8 *session_mac, guint32 session_id, const gchar *ip,
  96                 guint16 port, guint8 protocol, asp_session_port_status_e status,
  97                 gpointer user_data);
  98
  99 /*****************************************************************************
 100  * Functions Declaration
 101  *****************************************************************************/
 102
 103 /**
 104  * @brief initialize asp-session
 105  * @return void
 106  *
 107  * @paragraph <Example>
 108  * asp-seesion will be initialized.
 109  *
 110  * @verbatim
 111  * @endverbatim
 112 */
 113 gboolean asp_session_initialize(void);
 114
 115 /**
 116  * @brief deinitialize asp-session
 117  * @return void
 118  *
 119  * @paragraph <Example>
 120  * asp-seesion will be deinitialized.
 121  *
 122  * @verbatim
 123  * @endverbatim
 124 */
 125 gboolean asp_session_deinitialize(void);
 126
 127 /**
 128  * @brief ASP session method - ConnectSession over P2P
 129  * @param [in] service_mac p2p mac address of advertizer
 130  * @param [in] adv_id advertisement ID assigned by the ASP when the Advertise Service method is called
 131  * @param [in] session_info service-specific data payload(up to 144 bytes)
 132  * @param [in] info_length length of 'session_info' parameter
 133  * @param [in] network_role
 134  * @param [in] network_config
 135  * @param [out] session_mac mac address of the device that is calling this method
 136  * @param [out] session_id ID of newly created session.
 137  * @return gboolean
 138  *
 139  * @paragraph <Example>
 140  * asp-seesion will be deinitialized.
 141  *
 142  * @verbatim
 143  * @endverbatim
 144 */
 145 gboolean asp_session_connect_session_over_p2p(const guint8 *service_mac,
 146                 guint32 adv_id, const guint8 *session_info, size_t info_length,
 147                 guint8 network_role, guint8 network_config, guint8 *session_mac,
 148                 guint32 *session_id);
 149
 150 /**
 151  * @brief ASP session method - ConnectSession over infra
 152  * @param [in] peer_ip string type of peer's ip address like "111.222.333.444"
 153  * @param [in] adv_id advertisement ID assigned by the ASP when the AdvertiseService method is called
 154  * @param [in] session_info service-specific data payload(up to 144 bytes)
 155  * @param [in] length length of 'session_info' parameter
 156  * @param [out] session_mac mac address of the device that is calling this method
 157  * @param [out] session_id ID of newly created session.
 158  * @return gboolean
 159  *
 160  * @paragraph <Example>
 161  * asp-seesion will be deinitialized.
 162  *
 163  * @verbatim
 164  * @endverbatim
 165 */
 166 gboolean asp_session_connect_session_over_infra(const gchar *peer_ip,
 167                 guint32 adv_id, guint8 *session_info, size_t length,
 168                 guint8 *session_mac, guint32 *session_id);
 169
 170 /**
 171  * @brief ASP session method - ConfirmSession
 172  * @param [in] session_mac mac address of the device that assigned the value of session_id
 173  * @param [in] session_id ASP session ID assigned by the remote ASP
 174  * @param [in] confirmed TRUE or FALSE for session confirm
 175  * @param [in] pin required by SessionConfigRequest event
 176  * @return gboolean
 177  *
 178  * @paragraph <Example>
 179  * asp-session will process 2 cases by confirmed parameter.
 180  * in case of confrimed == TRUE => wait set_session_ready() from asp-manager
 181  * in case of confirmed == FALSE > send REJECTED_SESSION coordination protocol messasge to peer
 182  *
 183  * @verbatim
 184  * @endverbatim
 185 */
 186 gboolean asp_session_confirm_session(const guint8 *session_mac,
 187                 guint32 session_id, gboolean confirmed, guint32 pin);
 188
 189 /**
 190  * @brief ASP session method - SetSessionReady
 191  * @param [in] session_mac mac address of the device that assigned the value of session_id
 192  * @param [in] session_id ASP session ID assigned by the remote ASP
 193  * @return gboolean
 194  *
 195  * @paragraph <Example>
 196  * asp-session will send ADDED_SESSION coordination protocol message to peer
 197  *
 198  * @verbatim
 199  * @endverbatim
 200 */
 201 gboolean asp_session_set_session_ready(const guint8 *session_mac, guint32 session_id);
 202
 203 /**
 204  * @brief ASP session method - CloseSssion
 205  * @param [in] session_mac mac address of the device that assigned the value of session_id
 206  * @param [in] session_id ASP session ID assigned by the remote ASP
 207  * @param [in] reason reason of remove session
 208  * @return gboolean
 209  *
 210  * @paragraph <Example>
 211  * asp-session will send REMOVE_SESSION coordination protocol message to peer
 212  *
 213  * @verbatim
 214  * @endverbatim
 215 */
 216 gboolean asp_session_close_session(guint8 *session_mac, guint32 session_id,
 217                 asp_remove_session_reason_e reason);
 218
 219 /**
 220  * @brief ASP session method - BoundPort
 221  * @param [in] session_mac mac address of the device that assigned the value of session_id
 222  * @param [in] session_id ASP session ID assigned by the remote ASP
 223  * @param [in] ip IP address on which the port is being used
 224  * @param [in] port port number to be allowed
 225  * @param [in] protocol The IANA protocol number
 226  * @return gboolean
 227  *
 228  * @paragraph <Example>
 229  * asp-seesion will send ALLOWED_PORT coordination protocol message to peer
 230  *
 231  * @verbatim
 232  * @endverbatim
 233 */
 234 gboolean asp_session_bound_port(guint8 *session_mac, guint32 session_id,
 235                 const gchar *ip, guint16 port, guint8 protocol);
 236
 237 /**
 238  * @brief method to set a session to a deferred session
 239  * @param [in] session_mac mac address of the device that assigned the value of session_id
 240  * @param [in] session_id ASP session ID assigned by the remote ASP
 241  * @param [in] deferred_response reason of deferred session
 242  * @param [in] length length of 'deferred_response' parameter
 243  * @return gboolean
 244  *
 245  * @paragraph <Example>
 246  * asp-seesion will send DEFERRED_SESSION coordination protocol message to peer
 247  *
 248  * @verbatim
 249  * @endverbatim
 250 */
 251 gboolean asp_session_defer_session(guint8 *session_mac, guint32 session_id,
 252                 guint8 *deferred_response, size_t length);
 253
 254 /**
 255  * @brief method to get an advertisement MAC from a session
 256  * @param [in] session_mac mac address of the device that assigned the value of session_id
 257  * @param [in] session_id ASP session ID assigned by the remote ASP
 258  * @param [out] adv_mac advertisement MAC
 259  * @return gboolean
 260  *
 261  * @paragraph <Example>
 262  *
 263  * @verbatim
 264  * guint8 *adv_mac;
 265  * asp_session_get_advertisement_mac(session_mac, session_id, &adv_mac);
 266  * @endverbatim
 267 */
 268 gboolean asp_session_get_advertisement_mac(const guint8 *session_mac,
 269                 guint32 session_id, guint8 **adv_mac);
 270
 271 /**
 272  * @brief method to get an advertisement ID from a session
 273  * @param [in] session_mac mac address of the device that assigned the value of session_id
 274  * @param [in] session_id ASP session ID assigned by the remote ASP
 275  * @param [out] adv_id advertisement ID
 276  * @return gboolean
 277  *
 278  * @paragraph <Example>
 279  *
 280  * @verbatim
 281  * guint32 adv_id;
 282  * asp_session_get_advertisement_id(session_mac, session_id, &adv_id);
 283  * @endverbatim
 284 */
 285 gboolean asp_session_get_advertisement_id(const guint8 *session_mac,
 286                 guint32 session_id, guint32 *adv_id);
 287
 288 /**
 289  * @brief method to get a session state from a session
 290  * @param [in] session_mac mac address of the device that assigned the value of session_id
 291  * @param [in] session_id ASP session ID assigned by the remote ASP
 292  * @param [out] state current state of session. one of [OPEN, INITIATED, REQUESTED, CLOSE]
 293  * @return gboolean
 294  *
 295  * @paragraph <Example>
 296  *
 297  * @verbatim
 298  * asp_session_status_e state;
 299  * asp_session_get_state(session_mac, sessoin_id, &state);
 300  * @endverbatim
 301 */
 302 gboolean asp_session_get_state(guint8 *session_mac, guint32 session_id,
 303                 asp_session_status_e *state);
 304
 305 /**
 306  * @brief method to get ip & port of the peer.
 307  * @param [in] session_mac mac address of the device that assigned the value of session_id
 308  * @param [in] session_id ASP session ID assigned by the remote ASP
 309  * @param [out] peer_ip ip string
 310  * @param [out] port port num
 311  * @return gboolean
 312  *
 313  * @paragraph <Example>
 314  *
 315  * @verbatim
 316  * gchar ip[16]; // example of IPV4
 317  * guint16 port;
 318  * asp_session_get_peer_endpoint(session_mac, session_id, ip, &port);
 319  * @endverbatim
 320 */
 321 gboolean asp_session_get_peer_endpoint(guint8 *session_mac, guint32 session_id,
 322                 gchar *peer_ip, guint16 *port);
 323
 324 /**
 325  * @brief method to register a callback for ASP SessionReqeust event
 326  * @param [in] cb a callback for ASP SessionRequest event
 327  * @param [in] user_data callback user data
 328  * @return gboolean
 329  *
 330  * @paragraph <Example>
 331  * the registered callback will be triggered when session reqeust callback need to be called
 332  *
 333  * @verbatim
 334  * void my_cb(gint32 error_code, guint8* session_mac, guint32 session_id, guint32 adv_id, guint8* session_info, size_t length, gpointer user_data)
 335  * {
 336  * }
 337  * asp_session_set_session_request_cb(some_cb,
 338  * @endverbatim
 339 */
 340 gboolean asp_session_set_session_request_cb(asp_session_session_request_cb cb, gpointer user_data);
 341
 342 /**
 343  * @brief method to register a callback for ASP SessionConfigRequest event
 344  * @param [in] cb a callback for ASP SessionConfigRequest event
 345  * @param [in] user_data callback user data
 346  * @return gboolean
 347  *
 348  * @paragraph <Example>
 349  * the registered callback will be triggered when session request callback need to be called
 350  *
 351  * @verbatim
 352  * void my_cb (gint32 error_code, guint8* session_mac, guint32 session_id, gboolean get_pin, guint32 pin, gpointer user_data)
 353  * {
 354  * }
 355  * asp_session_set_session_config_request_cb(some_cb, (gpointer) user_data);
 356  * @endverbatim
 357 */
 358 gboolean asp_session_set_session_config_request_cb(asp_session_session_config_request_cb cb, gpointer user_data);
 359
 360 /**
 361  * @brief method to register a callback for ASP ConnectStatus event
 362  * @param [in] cb a callback for ASP ConnectStatus event
 363  * @param [in] user_data callback user data
 364  * @return gboolean
 365  *
 366  * @paragraph <Example>
 367  * the registered callback will be triggered when connect status callback need to be called
 368  *
 369  * @verbatim
 370  * void my_cb(gint32 error_code, const guint8* session_mac, guint32 session_id, asp_session_connect_status_e status, guint8* deferred_resp, size_t resp_length, gpointer user_data);
 371  * {
 372  * }
 373  * asp_session_set_connect_status_cb(some_cb, (gpointer) user_data);
 374  * @endverbatim
 375 */
 376 gboolean asp_session_set_connect_status_cb(asp_session_connect_status_cb cb, gpointer user_data);
 377
 378 /**
 379  * @brief method to register a callback for ASP SessionStatus event
 380  * @param [in] cb a callback for ASP SessionStatus event
 381  * @param [in] user_data callback user data
 382  * @return gboolean
 383  *
 384  * @paragraph <Example>
 385  * the registered callback will be triggered when connect status callback need to be called
 386  *
 387  * @verbatim
 388  * void my_cb(gint32 error_code, const guint8* session_mac, guint32 session_id, asp_session_status_e state, asp_session_closed_state_e status, const gchar* requested_info, gpointer user_data);
 389  * {
 390  * }
 391  * asp_session_set_session_request_cb(some_cb, (gpointer) user_data);
 392  * @endverbatim
 393 */
 394 gboolean asp_session_set_session_status_cb(asp_session_session_status_cb cb, gpointer user_data);
 395
 396 /**
 397  * @brief method to register a callback for ASP PortStatus event
 398  * @param [in] cb a callback for ASP PortStatus event
 399  * @param [in] user_data callback user data
 400  * @return gboolean
 401  *
 402  * @paragraph <Example>
 403  * the registered callback will be triggered when port status callback need to be called
 404  *
 405  * @verbatim
 406  * void my_cb(gint32 error_code, const guint8* session_mac, guint32 session_id, const gchar* peer_ip, guint16 port, guint8 protocol, asp_session_port_status_e status, gpointer user_data);
 407  * {
 408  * }
 409  * asp_session_set_session_request_cb(my_cb, (gpointer) user_data);
 410  * @endverbatim
 411 */
 412 gboolean asp_session_set_port_status_cb(asp_session_port_status_cb cb, gpointer user_data);
 413
 414 #ifdef __cplusplus
 415 }
 416 #endif
 417
 418 #endif                                                  /* __ASP_SESSION_H__ */