Add doxygen comments to connectivity module
[iotivity.git] / resource / csdk / connectivity / inc / caipnwmonitor.h
1 /******************************************************************
2  *
3  * Copyright 2016 Samsung Electronics All Rights Reserved.
4  *
5  *
6  *
7  * Licensed under the Apache License, Version 2.0 (the "License");
8  * you may not use this file except in compliance with the License.
9  * You may obtain a copy of the License at
10  *
11  *      http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing, software
14  * distributed under the License is distributed on an "AS IS" BASIS,
15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16  * See the License for the specific language governing permissions and
17  * limitations under the License.
18  *
19  ******************************************************************/
20
21 /**
22  * @file caipnwmonitor.h
23  * This file provides APIs IP network monitor modules.
24  */
25
26 #ifndef CA_IP_NW_INTERFACE_H_
27 #define CA_IP_NW_INTERFACE_H_
28
29 #include "cacommon.h"
30 #include "cathreadpool.h"
31 #include "uarraylist.h"
32
33 #ifdef __cplusplus
34 extern "C"
35 {
36 #endif
37
38 #define INTERFACE_NAME_MAX 16
39
40 /**
41  * Callback to be notified when IP adapter network state changes.
42  *
43  * @param[in]  adapter      Transport adapter.
44  * @param[in]  status       Connection status either ::CA_INTERFACE_UP or ::CA_INTERFACE_DOWN.
45  * @see CAIPSetConnectionStateChangeCallback() for registration.
46  */
47 typedef void (*CAIPAdapterStateChangeCallback)(CATransportAdapter_t adapter,
48                                                CANetworkStatus_t status);
49
50 /*
51  * Structure for IP address information, to be used to construct a CAEndpoint_t.  The
52  * structure name is a misnomer, as there is one entry per address not one per interface.
53  * An interface with 4 addresses should result in 4 instances of CAInterface_t.
54  */
55 typedef struct
56 {
57     char name[INTERFACE_NAME_MAX];
58     uint32_t index;
59     uint32_t flags;
60     uint16_t family;
61     char addr[MAX_ADDR_STR_SIZE_CA];
62 } CAInterface_t;
63
64 typedef struct CAIPCBData_t
65 {
66     struct CAIPCBData_t *next;               /**< pointer to next node */
67     CATransportAdapter_t adapter;            /**< transport adapter */
68     CAIPAdapterStateChangeCallback callback; /**< adapter state change callback */
69 } CAIPCBData_t;
70
71 /**
72  * Set callback for receiving local IP/TCP adapter connection status.
73  *
74  * @param[in]  callback     Callback to be notified when IP/TCP adapter connection state changes.
75  * @param[in]  adapter      Transport adapter.
76  * @return ::CA_STATUS_OK or Appropriate error code.
77  */
78 CAResult_t CAIPSetNetworkMonitorCallback(CAIPAdapterStateChangeCallback callback,
79                                          CATransportAdapter_t adapter);
80
81 /**
82  * Unset callback for receiving local IP/TCP adapter connection status.
83  *
84  * @param[in]  adapter      Transport adapter.
85  * @return ::CA_STATUS_OK or Appropriate error code.
86  */
87 CAResult_t CAIPUnSetNetworkMonitorCallback(CATransportAdapter_t adapter);
88
89 /**
90  * Get a list of CAInterface_t items.
91  *
92  * @param[in]  desiredIndex      Network interface index.
93  * @return  List of CAInterface_t items.
94  */
95 u_arraylist_t *CAIPGetInterfaceInformation(int desiredIndex);
96
97 /**
98  * Find network interface changes.
99  *
100  * @return  List of CAInterface_t items.
101  */
102 u_arraylist_t *CAFindInterfaceChange(void);
103
104 /**
105  * Start network monitor.
106  *
107  * @param[in]  callback     Callback to be notified when IP/TCP adapter connection state changes.
108  * @param[in]  adapter      Transport adapter.
109  * @return ::CA_STATUS_OK or Appropriate error code.
110  */
111 CAResult_t CAIPStartNetworkMonitor(CAIPAdapterStateChangeCallback callback,
112                                    CATransportAdapter_t adapter);
113
114 /**
115  * Stops network monitor.
116  *
117  * @param[in]  adapter      Transport adapter.
118  * @return ::CA_STATUS_OK or Appropriate error code.
119  */
120 CAResult_t CAIPStopNetworkMonitor(CATransportAdapter_t adapter);
121
122 /**
123  * Apply network interface changes.
124  *
125  * @param[in]  ifchanged      Changed interface.
126  */
127 void CAProcessNewInterface(CAInterface_t *ifchanged);
128
129 /**
130  * This function return link local zone id related from ifindex.
131  *
132  * @param ifindex[in]     interface index.
133  * @param zoneId[out]     pointer of zoneId string, caller should free
134  *                        zoneId using OICFree() when it returned CA_STATUS_OK.
135  * @return  ::CA_STATUS_OK or ::CA_STATUS_INVALID_PARAM
136  */
137 CAResult_t CAGetLinkLocalZoneIdInternal(uint32_t ifindex, char **zoneId);
138
139 #ifdef __cplusplus
140 }
141 #endif
142
143 #endif /* CA_IP_NW_INTERFACE_H_ */