1 /* 2 * Copyright (c) 2017-2019, Texas Instruments Incorporated 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * 9 * * Redistributions of source code must retain the above copyright 10 * notice, this list of conditions and the following disclaimer. 11 * 12 * * Redistributions in binary form must reproduce the above copyright 13 * notice, this list of conditions and the following disclaimer in the 14 * documentation and/or other materials provided with the distribution. 15 * 16 * * Neither the name of Texas Instruments Incorporated nor the names of 17 * its contributors may be used to endorse or promote products derived 18 * from this software without specific prior written permission. 19 * 20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 */ 32 33 /*****************************************************************************/ 34 /* Include files */ 35 /*****************************************************************************/ 36 37 #ifndef __SL_NET_IF_H__ 38 #define __SL_NET_IF_H__ 39 40 #include <stdint.h> 41 #include <stdbool.h> 42 43 #include <ti/net/slnetsock.h> 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 49 /*! 50 \defgroup SlNetIf SlNetIf group 51 52 \short Controls standard stack/interface options and capabilities 53 54 */ 55 /*! 56 \addtogroup SlNetIf 57 @{ 58 */ 59 60 /*****************************************************************************/ 61 /* Macro declarations */ 62 /*****************************************************************************/ 63 64 /* Interface ID bit pool to be used in interface add and in socket creation */ 65 #define SLNETIF_ID_1 (1 << 0) /**< Interface ID 1 */ 66 #define SLNETIF_ID_2 (1 << 1) /**< Interface ID 2 */ 67 #define SLNETIF_ID_3 (1 << 2) /**< Interface ID 3 */ 68 #define SLNETIF_ID_4 (1 << 3) /**< Interface ID 4 */ 69 #define SLNETIF_ID_5 (1 << 4) /**< Interface ID 5 */ 70 #define SLNETIF_ID_6 (1 << 5) /**< Interface ID 6 */ 71 #define SLNETIF_ID_7 (1 << 6) /**< Interface ID 7 */ 72 #define SLNETIF_ID_8 (1 << 7) /**< Interface ID 8 */ 73 #define SLNETIF_ID_9 (1 << 8) /**< Interface ID 9 */ 74 #define SLNETIF_ID_10 (1 << 9) /**< Interface ID 10 */ 75 #define SLNETIF_ID_11 (1 << 10) /**< Interface ID 11 */ 76 #define SLNETIF_ID_12 (1 << 11) /**< Interface ID 12 */ 77 #define SLNETIF_ID_13 (1 << 12) /**< Interface ID 13 */ 78 #define SLNETIF_ID_14 (1 << 13) /**< Interface ID 14 */ 79 #define SLNETIF_ID_15 (1 << 14) /**< Interface ID 15 */ 80 #define SLNETIF_ID_16 (1 << 15) /**< Interface ID 16 */ 81 82 #define SLNETIF_MAX_IF (16) /**< Maximum interface */ 83 84 /* this macro returns 0 when only one bit is set and a number when it isn't */ 85 #define ONLY_ONE_BIT_IS_SET(x) (((x > 0) && ((x & (x - 1)) == 0))?true:false) 86 87 88 /* Interface connection status bit pool to be used in set interface connection status function */ 89 90 #define SLNETIF_STATUS_DISCONNECTED (0) 91 #define SLNETIF_STATUS_CONNECTED (1) 92 93 /*! 94 \brief Interface state bit pool to be used in set interface state function 95 */ 96 typedef enum 97 { 98 SLNETIF_STATE_DISABLE = 0, 99 SLNETIF_STATE_ENABLE = 1 100 } SlNetIfState_e; 101 102 /*! 103 \brief Address type enum to be used in get ip address function 104 */ 105 typedef enum 106 { 107 SLNETIF_IPV4_ADDR = 0, 108 SLNETIF_IPV6_ADDR_LOCAL = 1, 109 SLNETIF_IPV6_ADDR_GLOBAL = 2 110 } SlNetIfAddressType_e; 111 112 /* Address config return values that can be retrieved in get ip address function */ 113 #define SLNETIF_ADDR_CFG_UNKNOWN (0) 114 #define SLNETIF_ADDR_CFG_DHCP (1) 115 #define SLNETIF_ADDR_CFG_DHCP_LLA (2) 116 #define SLNETIF_ADDR_CFG_STATIC (4) 117 #define SLNETIF_ADDR_CFG_STATELESS (5) 118 #define SLNETIF_ADDR_CFG_STATEFUL (6) 119 120 /* Security object types for load Sec Obj function */ 121 #define SLNETIF_SEC_OBJ_TYPE_RSA_PRIVATE_KEY (1) 122 #define SLNETIF_SEC_OBJ_TYPE_CERTIFICATE (2) 123 #define SLNETIF_SEC_OBJ_TYPE_DH_KEY (3) 124 125 126 /*! 127 Check if interface state is enabled. 128 129 \sa SlNetIf_queryIf() 130 */ 131 #define SLNETIF_QUERY_IF_STATE_BIT (1 << 0) 132 /*! 133 Check if interface connection status is connected. 134 135 \sa SlNetIf_queryIf() 136 */ 137 #define SLNETIF_QUERY_IF_CONNECTION_STATUS_BIT (1 << 1) 138 /*! 139 Enable last partial match in an interface search, if no existing 140 interface matches the query completely. 141 142 \sa SlNetIf_queryIf() 143 */ 144 #define SLNETIF_QUERY_IF_ALLOW_PARTIAL_MATCH_BIT (1 << 2) 145 146 /*****************************************************************************/ 147 /* Structure/Enum declarations */ 148 /*****************************************************************************/ 149 150 /*! 151 \brief SlNetIf_Config_t structure contains all the function callbacks that are expected to be filled by the relevant network stack interface \n 152 Each interface has different capabilities, so not all the API's must be supported therefore an API's can be defined as: 153 - <b>Mandatory API's</b> - must be supported by the interface in order to be part of SlNetSock layer 154 - <b>Non-Mandatory API's</b> - can be supported, but not mandatory for basic SlNetSock proper operation 155 156 \note Interface that is not supporting a non-mandatory API should set it to \b NULL in its function list 157 158 \sa SlNetIf_Config_t 159 */ 160 typedef struct SlNetIf_Config_t 161 { 162 /* socket related API's */ 163 int16_t (*sockCreate) (void *ifContext, int16_t domain, int16_t type, int16_t protocol, void **sdContext); /*!< \b Mandatory API \n The actual implementation of the interface for ::SlNetSock_create */ 164 int32_t (*sockClose) (int16_t sd, void *sdContext); /*!< \b Mandatory API \n The actual implementation of the interface for ::SlNetSock_close */ 165 int32_t (*sockShutdown) (int16_t sd, void *sdContext, int16_t how); /*!< \b Non-Mandatory API \n The actual implementation of the interface for ::SlNetSock_shutdown */ 166 int16_t (*sockAccept) (int16_t sd, void *sdContext, SlNetSock_Addr_t *addr, SlNetSocklen_t *addrlen, uint8_t flags, void **acceptedSdContext); /*!< \b Non-Mandatory API \n The actual implementation of the interface for ::SlNetSock_accept */ 167 int32_t (*sockBind) (int16_t sd, void *sdContext, const SlNetSock_Addr_t *addr, int16_t addrlen); /*!< \b Non-Mandatory API \n The actual implementation of the interface for ::SlNetSock_bind */ 168 int32_t (*sockListen) (int16_t sd, void *sdContext, int16_t backlog); /*!< \b Non-Mandatory API \n The actual implementation of the interface for ::SlNetSock_listen */ 169 int32_t (*sockConnect) (int16_t sd, void *sdContext, const SlNetSock_Addr_t *addr, SlNetSocklen_t addrlen, uint8_t flags); /*!< \b Non-Mandatory API \n The actual implementation of the interface for ::SlNetSock_connect */ 170 int32_t (*sockGetPeerName) (int16_t sd, void *sdContext, SlNetSock_Addr_t *addr, SlNetSocklen_t *addrlen); /*!< \b Non-Mandatory API \n The actual implementation of the interface for ::SlNetSock_getPeerName */ 171 int32_t (*sockGetLocalName) (int16_t sd, void *sdContext, SlNetSock_Addr_t *addr, SlNetSocklen_t *addrlen); /*!< \b Non-Mandatory API \n The actual implementation of the interface for ::SlNetSock_getSockName */ 172 int32_t (*sockSelect) (void *ifContext, int16_t nsds, SlNetSock_SdSet_t *readsds, SlNetSock_SdSet_t *writesds, SlNetSock_SdSet_t *exceptsds, SlNetSock_Timeval_t *timeout); /*!< \b Mandatory API \n The actual implementation of the interface for ::SlNetSock_select */ 173 int32_t (*sockSetOpt) (int16_t sd, void *sdContext, int16_t level, int16_t optname, void *optval, SlNetSocklen_t optlen); /*!< \b Mandatory API \n The actual implementation of the interface for ::SlNetSock_setOpt */ 174 int32_t (*sockGetOpt) (int16_t sd, void *sdContext, int16_t level, int16_t optname, void *optval, SlNetSocklen_t *optlen); /*!< \b Mandatory API \n The actual implementation of the interface for ::SlNetSock_getOpt */ 175 int32_t (*sockRecv) (int16_t sd, void *sdContext, void *buf, uint32_t len, uint32_t flags); /*!< \b Non-Mandatory API \n The actual implementation of the interface for ::SlNetSock_recv */ 176 int32_t (*sockRecvFrom) (int16_t sd, void *sdContext, void *buf, uint32_t len, uint32_t flags, SlNetSock_Addr_t *from, SlNetSocklen_t *fromlen); /*!< \b Mandatory API \n The actual implementation of the interface for ::SlNetSock_recvFrom */ 177 int32_t (*sockSend) (int16_t sd, void *sdContext, const void *buf, uint32_t len, uint32_t flags); /*!< \b Non-Mandatory API \n The actual implementation of the interface for ::SlNetSock_send */ 178 int32_t (*sockSendTo) (int16_t sd, void *sdContext, const void *buf, uint32_t len, uint32_t flags, const SlNetSock_Addr_t *to, SlNetSocklen_t tolen); /*!< \b Mandatory API \n The actual implementation of the interface for ::SlNetSock_sendTo */ 179 int32_t (*sockstartSec) (int16_t sd, void *sdContext, SlNetSockSecAttrib_t *secAttrib, uint8_t flags); /*!< \b Non-Mandatory API \n The actual implementation of the interface for ::SlNetSock_startSec */ 180 181 /* util related API's */ 182 int32_t (*utilGetHostByName) (void *ifContext, char *name, const uint16_t nameLen, uint32_t *ipAddr, uint16_t *ipAddrLen, const uint8_t family); /*!< \b Non-Mandatory API \n The actual implementation of the interface for ::SlNetUtil_getHostByName */ 183 184 /* if related API's */ 185 int32_t (*ifGetIPAddr) (void *ifContext, SlNetIfAddressType_e addrType, uint16_t *addrConfig, uint32_t *ipAddr); /*!< \b Mandatory API \n The actual implementation of the interface for ::SlNetIf_getIPAddr */ 186 int32_t (*ifGetConnectionStatus) (void *ifContext); /*!< \b Mandatory API \n The actual implementation of the interface for ::SlNetIf_getConnectionStatus */ 187 int32_t (*ifLoadSecObj) (void *ifContext, uint16_t objType, char *objName, int16_t objNameLen, uint8_t *objBuff, int16_t objBuffLen); /*!< \b Non-Mandatory API \n The actual implementation of the interface for ::SlNetIf_loadSecObj */ 188 int32_t (*ifCreateContext) (uint16_t ifID, const char *ifName, void **ifContext); /*!< \b Non-Mandatory API \n The actual implementation of the interface for ::SlNetIf_add */ 189 190 } SlNetIf_Config_t; 191 192 193 /*! 194 \brief The SlNetIf_t structure holds the configuration of the interface 195 Its ID, name, flags and the configuration list - ::SlNetIf_Config_t. 196 */ 197 typedef struct SlNetIf_t 198 { 199 uint32_t ifID; 200 char *ifName; 201 int32_t flags; 202 SlNetIf_Config_t *ifConf; 203 void *ifContext; 204 } SlNetIf_t; 205 206 /*****************************************************************************/ 207 /* Function prototypes */ 208 /*****************************************************************************/ 209 210 /*! 211 212 \brief Initialize the SlNetIf module 213 214 \param[in] flags For future usage, 215 The value 0 may be used in order to run the 216 default flags 217 218 \return Zero on success, or negative error code on failure 219 220 \par Examples 221 \snippet ti/net/test/snippets/slnetif.c SlNetIf_init snippet 222 */ 223 int32_t SlNetIf_init(int32_t flags); 224 225 /*! 226 \brief Add a new SlNetIf-compatible interface to the system 227 228 The SlNetIf_add function allows the application to add specific interfaces 229 with their priorities and function list.\n 230 This function gives full control to the application on the interfaces. 231 232 \param[in] ifID Specifies the interface which needs 233 to be added.\n 234 The values of the interface identifier 235 is defined with the prefix SLNETIF_ID_ 236 which defined in slnetif.h 237 \param[in] ifName Specifies the name of the interface, 238 \b Note: Can be set to NULL, but when set to NULL 239 cannot be used with SlNetIf_getIDByName() 240 \param[in] ifConf Specifies the function list for the 241 interface 242 \param[in] priority Specifies the priority of the interface 243 (In ascending order). 244 Note: maximum priority is 15 245 246 \return Zero on success, or negative error code on failure 247 248 \slnetif_not_threadsafe 249 250 \par Examples 251 \snippet ti/net/test/snippets/slnetif.c SlNetIf_add wifi snippet 252 \snippet ti/net/test/snippets/slnetif.c SlNetIf_add NDK snippet 253 \snippet ti/net/test/snippets/slnetif.c SlNetIf_add NDKSec snippet 254 */ 255 int32_t SlNetIf_add(uint16_t ifID, char *ifName, const SlNetIf_Config_t *ifConf, uint8_t priority); 256 257 258 /*! 259 \brief Get interface configuration from interface ID 260 261 The SlNetIf_getIfByID function retrieves the configuration of the 262 requested interface. 263 264 \param[in] ifID Specifies the interface which its configuration 265 needs to be retrieved.\n 266 The values of the interface identifier is 267 defined with the prefix SLNETIF_ID_ which 268 defined in slnetif.h 269 270 \return A pointer to the configuration of the 271 interface on success, or NULL on failure 272 273 \sa SlNetIf_add() 274 275 \slnetif_not_threadsafe 276 277 \par Examples 278 \snippet ti/net/test/snippets/slnetif.c SlNetIf_getIfByID snippet 279 */ 280 SlNetIf_t * SlNetIf_getIfByID(uint16_t ifID); 281 282 283 /*! 284 \brief Query for the highest priority interface, given a list of 285 interfaces and properties. 286 287 \param[in] ifBitmap The bit-wise OR of interfaces to be searched.\n 288 Note: Zero is currently not valid. 289 \param[in] queryBitmap The bit-wise OR of additional query criteria. 290 291 \remarks @c queryBitmap can be set to : 292 - #SLNETIF_QUERY_IF_STATE_BIT 293 - #SLNETIF_QUERY_IF_CONNECTION_STATUS_BIT 294 - #SLNETIF_QUERY_IF_ALLOW_PARTIAL_MATCH_BIT 295 296 \return A pointer to the configuration of a found 297 interface on success, or NULL on failure 298 299 \sa SlNetIf_add() 300 \slnetif_not_threadsafe 301 302 \par Examples 303 \snippet ti/net/test/snippets/slnetif.c SlNetIf_queryIf snippet 304 */ 305 SlNetIf_t * SlNetIf_queryIf(uint32_t ifBitmap, uint32_t queryBitmap); 306 307 308 /*! 309 \brief Get interface Name from interface ID 310 311 The SlNetIf_getNameByID function retrieves the name of the requested 312 interface. 313 314 \param[in] ifID Specifies the interface which its name needs 315 to be retrieved.\n 316 The values of the interface identifier is 317 defined with the prefix SLNETIF_ID_ which 318 defined in slnetif.h 319 320 \return A pointer to the name of the interface on 321 success, or NULL on failure 322 323 \sa SlNetIf_add() 324 \sa SlNetIf_getIDByName() 325 326 \slnetif_not_threadsafe 327 328 \par Examples 329 \snippet ti/net/test/snippets/slnetif.c SlNetIf_getNameByID snippet 330 */ 331 const char * SlNetIf_getNameByID(uint16_t ifID); 332 333 334 /*! 335 \brief Get interface ID from interface name 336 337 The SlNetIf_getIDByName function retrieves the interface identifier of the 338 requested interface name. 339 340 \param[in] ifName Specifies the interface which its interface 341 identifier needs to be retrieved.\n 342 343 \return The interface identifier value of the interface 344 on success, or negative error code on failure 345 The values of the interface identifier is 346 defined with the prefix SLNETIF_ID_ which 347 defined in slnetif.h 348 349 \sa SlNetIf_add() 350 \sa SlNetIf_getNameByID() 351 \sa SlNetSock_getIfID() 352 353 \note - Input NULL as ifName will return error code. 354 - When using more than one interface with the same 355 name, the ID of the highest priority interface 356 will be returned 357 \slnetif_not_threadsafe 358 359 \par Examples 360 \snippet ti/net/test/snippets/slnetif.c SlNetIf_getIDByName snippet 361 */ 362 int32_t SlNetIf_getIDByName(char *ifName); 363 364 365 /*! 366 \brief Get interface priority 367 368 The SlNetIf_getPriority function retrieves the priority of the 369 interface. 370 371 \param[in] ifID Specifies the interface which its priority 372 needs to be retrieved.\n 373 The values of the interface identifier is 374 defined with the prefix SLNETIF_ID_ which 375 defined in slnetif.h 376 377 \return The priority value of the interface on success, 378 or negative error code on failure 379 380 \sa SlNetIf_add() 381 \sa SlNetIf_setPriority() 382 383 \slnetif_not_threadsafe 384 385 \par Examples 386 \snippet ti/net/test/snippets/slnetif.c SlNetIf_getPriority snippet 387 */ 388 int32_t SlNetIf_getPriority(uint16_t ifID); 389 390 391 /*! 392 \brief Set interface priority 393 394 The SlNetIf_setPriority function sets new priority to the requested interface. 395 396 \param[in] ifID Specifies the interface which its priority 397 needs to be changed.\n 398 The values of the interface identifier is 399 defined with the prefix SLNETIF_ID_ which 400 defined in slnetif.h 401 \param[in] priority Specifies the priority needs to be set. 402 (In ascending order) 403 Note: maximum priority is 15 404 405 \return Zero on success, or negative error code on 406 failure 407 408 \sa SlNetIf_add() 409 \sa SlNetIf_getPriority() 410 411 \slnetif_not_threadsafe 412 413 \par Examples 414 \snippet ti/net/test/snippets/slnetif.c SlNetIf_setPriority snippet 415 */ 416 int32_t SlNetIf_setPriority(uint16_t ifID, uint8_t priority); 417 418 419 /*! 420 \brief Set interface state 421 422 Enable or disable the interface. 423 424 \param[in] ifID Specifies the interface which its state 425 needs to be changed.\n 426 The values of the interface identifier is 427 defined with the prefix SLNETIF_ID_ which 428 defined in slnetif.h 429 \param[in] ifState Specifies the interface state.\n 430 The values of the interface state are defined 431 with the prefix SLNETIF_INTERFACE_ which 432 defined in slnetif.h 433 434 \return Zero on success, or negative error code on 435 failure 436 437 \sa SlNetIf_add() 438 \sa SlNetIf_getState() 439 440 \slnetif_not_threadsafe 441 442 \par Examples 443 \snippet ti/net/test/snippets/slnetif.c SlNetIf_setState snippet 444 */ 445 int32_t SlNetIf_setState(uint16_t ifID, SlNetIfState_e ifState); 446 447 448 /*! 449 \brief Get interface state 450 451 Obtain the current state of the interface. 452 453 \param[in] ifID Specifies the interface which its state needs 454 to be retrieved.\n 455 The values of the interface identifier is 456 defined with the prefix SLNETIF_ID_ which 457 defined in slnetif.h 458 459 \return State of the interface on success, or negative 460 error code on failure 461 462 \sa SlNetIf_add() 463 \sa SlNetIf_setState() 464 465 \slnetif_not_threadsafe 466 467 \par Examples 468 \snippet ti/net/test/snippets/slnetif.c SlNetIf_getState snippet 469 */ 470 int32_t SlNetIf_getState(uint16_t ifID); 471 472 473 /*! 474 \brief Get the connection status of an interface 475 476 \param[in] ifID Interface ID 477 478 \return @c SLNETIF_STATUS_ value on success, 479 or negative error code on failure 480 481 \remark @c ifID should be a value with the @c SLNETIF_ID_ 482 prefix 483 484 \sa SlNetIf_add() 485 \sa SLNETIF_STATUS_CONNECTED 486 \sa SLNETIF_STATUS_DISCONNECTED 487 488 \slnetif_not_threadsafe 489 490 \par Examples 491 \snippet ti/net/test/snippets/slnetif.c SlNetIf_getConnectionStatus snippet 492 */ 493 int32_t SlNetIf_getConnectionStatus(uint16_t ifID); 494 495 496 /*! 497 \brief Get IP Address of specific interface 498 499 The SlNetIf_getIPAddr function retrieve the IP address of a specific 500 interface according to the Address Type, IPv4, IPv6 LOCAL 501 or IPv6 GLOBAL. 502 503 \param[in] ifID Specifies the interface which its connection 504 state needs to be retrieved.\n 505 The values of the interface identifier is 506 defined with the prefix SLNETIF_ID_ which 507 defined in slnetif.h 508 \param[in] addrType Address type: 509 - #SLNETIF_IPV4_ADDR 510 - #SLNETIF_IPV6_ADDR_LOCAL 511 - #SLNETIF_IPV6_ADDR_GLOBAL 512 \param[out] addrConfig Address config: 513 - #SLNETIF_ADDR_CFG_UNKNOWN 514 - #SLNETIF_ADDR_CFG_DHCP 515 - #SLNETIF_ADDR_CFG_DHCP_LLA 516 - #SLNETIF_ADDR_CFG_STATIC 517 - #SLNETIF_ADDR_CFG_STATELESS 518 - #SLNETIF_ADDR_CFG_STATEFUL 519 \param[out] ipAddr IP Address according to the Address Type 520 521 \return Zero on success, or negative error code on failure 522 523 \sa SlNetIfAddressType_e 524 525 \slnetif_not_threadsafe 526 527 \par Examples 528 \snippet ti/net/test/snippets/slnetif.c SlNetIf_getIPAddr snippet 529 */ 530 int32_t SlNetIf_getIPAddr(uint16_t ifID, SlNetIfAddressType_e addrType, uint16_t *addrConfig, uint32_t *ipAddr); 531 532 533 /*! 534 \brief Load/unload/replace a secure object into a network interface/stack 535 536 SlNetIf_loadSecObj() loads a named secure object into specific 537 network stack for future use by secure sockets. To unload the 538 named secure object, pass a NULL object buffer with the 539 appropriate name. 540 541 \param[in] objType The secure object type: 542 - #SLNETIF_SEC_OBJ_TYPE_RSA_PRIVATE_KEY 543 - #SLNETIF_SEC_OBJ_TYPE_CERTIFICATE 544 - #SLNETIF_SEC_OBJ_TYPE_DH_KEY 545 \param[in] objName The secure object name 546 \param[in] objNameLen The secure object name length 547 \param[in] objBuff The secure object buffer to be loaded, or 548 NULL if the named object is to be unloaded 549 \param[in] objBuffLen The secure object buffer length 550 \param[in] ifBitmap The interfaces which the secure 551 objects should be loaded to 552 553 \remark Loaded secure objects are added to secure attributes using 554 the SlNetSock_secAttribCreate(), 555 SlNetSock_secAttribSet(), and 556 SlNetSock_secAttribDelete() lifecycle APIs. The 557 loading/unloading of secure objects (via 558 SlNetIf_loadSecObj()) must be done while the secure 559 object is not associated with any existing secure 560 attributes. Restating, you must delete any existing 561 secure attributes before changing any secure objects 562 associated with them. 563 564 \remark The values of @c ifBitmap typically have the prefix 565 @c SLNETIF_ID_. 566 567 \remark SlNetIf_loadSecObj() internally validates the @c objName, 568 @c objNameLen, and @c objType arguments, so the 569 underlying interface/stack functions do not need to 570 check them again. 571 572 \remark For stacks that use file systems (e.g. CC3XXX), @c objName 573 will be the file name used on the file system. 574 575 \remark Note that ownership of @c objBuff after returning from 576 SlNetIf_loadSecObj() varies by stack/interface, often 577 depending on how the underlying stack implements it's 578 TLS support. 579 - On CC3XXX-based stacks, the TLS support is managed 580 on a separate network processor, and loading a 581 secure object results in persisting the secure 582 object to a file system. As a result, after 583 successfully calling SlNetIf_loadSecObj(), the @c 584 objBuff is no longer needed, and can be considered 585 "owned" by the application. 586 587 - On NDK-based stacks, the TLS support is typically 588 managed by a software library like mbedTLS. As a 589 result, only a reference to @c objBuff is made 590 within the SlNetIf_loadSecObj() call, and the 591 buffer must persist as long as the secure object 592 remains loaded. Ownership of the buffer returns 593 to the user only after unloading the secure 594 object (or resetting the device). 595 596 \remark To replace an existing named secure object with another 597 secure object of the same name, call 598 SlNetIf_loadSecObj() with the same @c objName. 599 Resources associated with the previously loaded secure 600 object will be released and replaced by the new secure 601 object. 602 603 \remark When unloading a named secure object, @c objBuffLen is 604 ignored. 605 606 \return 0 on success, negative on failure. Common errors include: 607 - #SLNETERR_RET_CODE_INVALID_INPUT 608 - #SLNETERR_RET_CODE_NO_FREE_SPACE 609 - #SLNETERR_RET_CODE_MALLOC_ERROR 610 611 \sa SlNetSock_setOpt() 612 \sa SlNetSock_secAttribSet() 613 614 \slnetif_not_threadsafe 615 616 */ 617 int32_t SlNetIf_loadSecObj(uint16_t objType, char *objName, int16_t objNameLen, uint8_t *objBuff, int16_t objBuffLen, uint32_t ifBitmap); 618 619 /*! 620 621 Close the Doxygen group. 622 @} 623 624 */ 625 626 #ifdef __cplusplus 627 } 628 #endif /* __cplusplus */ 629 630 #endif /* __SL_NET_IF_H__ */ 631
