diff --git a/CHANGELOG.md b/CHANGELOG.md index 6258ac71..c7084871 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,8 +4,19 @@ All notable changes to this project will be documented in this file. Dates are d Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog). +#### [1.4.1](https://github.com/rdkcentral/utopia/compare/1.4.0...1.4.1) + +- RDKCOM-5484: RDKBDEV-3327 Add API documentation for Utopia Header files [`#146`](https://github.com/rdkcentral/utopia/pull/146) +- XF10-229 XF10-281 : Analyse & Add support for hotspot 6G [`#153`](https://github.com/rdkcentral/utopia/pull/153) +- [RDKB-62642] Parental control is not working as expected - iptables broken with chain create error [`#141`](https://github.com/rdkcentral/utopia/pull/141) +- RDKCOM-5473: RDKBACCL-1248 rdkb-cli connection was not established from bpi device via 8888 port [`#140`](https://github.com/rdkcentral/utopia/pull/140) +- RDKB-61944 : [Coverity] Various issues in utopia - part2 [`#137`](https://github.com/rdkcentral/utopia/pull/137) +- Merge tag '1.4.0' into develop [`e7e3d74`](https://github.com/rdkcentral/utopia/commit/e7e3d74f962a08833dbe73ad1a951d7abe87bd16) + #### [1.4.0](https://github.com/rdkcentral/utopia/compare/1.3.1...1.4.0) +> 4 December 2025 + - RDKB-61489: {Ignite} Router advertisement packet has been dropped via firewall at runtime. [`#139`](https://github.com/rdkcentral/utopia/pull/139) - RDKB-62206 - Rename NTP Telemetry Marker [`#133`](https://github.com/rdkcentral/utopia/pull/133) - IPV6 hotspot support for ETHWAN mode and Other Platform [`#124`](https://github.com/rdkcentral/utopia/pull/124) diff --git a/source/dhcpproxy/dhcp_msg.h b/source/dhcpproxy/dhcp_msg.h index 7721b5dc..53d4b198 100644 --- a/source/dhcpproxy/dhcp_msg.h +++ b/source/dhcpproxy/dhcp_msg.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -99,7 +99,7 @@ struct dhcp_option * @brief DHCP option code */ enum { - OPTION_PAD=0, + OPTION_PAD=0, OPTION_ROUTER=3, OPTION_DNS=6, OPTION_HOSTNAME=12, @@ -152,26 +152,116 @@ enum { extern "C" { #endif +/** +* @brief Compare two DHCP options. +* +* This function compares two DHCP option structures by their length and data. +* +* @param[in] opt1 - Pointer to the first DHCP option to compare. +* @param[in] opt2 - Pointer to the second DHCP option to compare. +* +* @return The comparison result. +* @retval 0 if two options are same. +* @retval -1 if opt1 is less than opt2. +* @retval 1 if opt1 is greater than opt2. +* +*/ int compare_option(const struct dhcp_option *opt1, const struct dhcp_option *opt2); +/** +* @brief Copy DHCP option and allocate new memory for data. +* +* This function performs copy of a DHCP option from src to dst. +* +* @param[in,out] dst - Pointer to the destination DHCP option structure. +* @param[in] src - Pointer to the source DHCP option structure to copy from. +* +* @return None. +* +*/ void dhcp_copy_option(struct dhcp_option *dst, const struct dhcp_option *src); +/** +* @brief Cleanup DHCP option by freeing allocated memory. +* +* This function can only be used to clean up copied DHCP options. DHCP options from message parsing contain pointers to option +* locations inside the DHCP message and cannot be cleaned using this function.This function does not free the option structure itself. +* +* @param[in,out] opt - Pointer to the DHCP option structure to cleanup. +* +* @return None. +* +*/ void dhcp_cleanup_option(struct dhcp_option *opt); +/** +* @brief Clear DHCP option info and free all associated option lists. +* +* This function releases all dynamically allocated option nodes and resets the structure to zero. +* +* @param[in,out] opt_info - Pointer to the DHCP option info structure to clear. +* +* @return None. +* +*/ void dhcp_clear_option_info(struct dhcp_option_info *opt_info); +/** +* @brief Parse a list of DHCP options from option data. +* +* @param[in,out] opt_info - Pointer to DHCP option info structure where parsed options will be stored. +* Overload flag will be set if found. +* @param[in] opt_data - Pointer to the option data buffer to parse. +* @param[in] size - Size of the option data buffer in bytes. +* +* @return A linked list of DHCP options. +* +*/ struct dhcp_option *dhcp_parse_options(struct dhcp_option_info *opt_info, ui8* opt_data, size_t size); +/** +* @brief Parse DHCP message including options in option field, file field, and sname field. +* +* @param[out] opt_info - Pointer to DHCP option info structure where parsed options will be stored. +* @param[in] msg - Pointer to the DHCP message to parse. +* @param[in] size - Total size of the DHCP message in bytes. +* +* @return None. +* +*/ void dhcp_parse_msg(struct dhcp_option_info *opt_info, struct dhcp_msg *msg, size_t size); +/** +* @brief Validate DHCP message by checking message type consistency with operation type. +* +* @param[in] msg - Pointer to the DHCP message to validate. +* @param[in] opt_info - Pointer to the DHCP option info containing parsed message type. +* +* @return The status of the operation. +* @retval 0 if the message is valid. +* @retval -1 if the message is invalid. +* +*/ int dhcp_validate_msg(const struct dhcp_msg *msg, const struct dhcp_option_info *opt_info); +/** +* @brief Add a single IP address option to the buffer. +* +* This function add a 4-byte IP address option into the provided buffer. +* +* @param[in] code - DHCP option code. +* @param[in] ipaddr - IP address to add. +* @param[out] buf - Pointer to the buffer where the option will be written. +* @param[in] bufsize - Size of the buffer in bytes. +* +* @return The number of bytes written to the buffer. +* +*/ size_t dhcp_add_ipaddr_option(ui8 code, struct in_addr ipaddr, ui8* buf, size_t bufsize); #ifdef __cplusplus } #endif -#endif // _DHCP_MSG_H_ - +#endif // _DHCP_MSG_H_ \ No newline at end of file diff --git a/source/dhcpproxy/dhcp_proxy.h b/source/dhcpproxy/dhcp_proxy.h index 8f0ea052..ced7c813 100644 --- a/source/dhcpproxy/dhcp_proxy.h +++ b/source/dhcpproxy/dhcp_proxy.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -99,19 +99,78 @@ extern struct in_addr g_my_ip; extern "C" { #endif +/** +* @brief Find DHCP lease associated with a DHCP message. +* +* This function lookup an existing DHCP lease by client identifier if present, otherwise by hardware type and chaddr. +* +* @param[in] msg - Pointer to the DHCP message used for lease lookup. +* @param[in] opt_info - Pointer to DHCP option info containing client identifier. +* @param[out] pprev - Pointer to store the previous lease in the list. +* +* @return DHCP lease found associated with a DHCP message. +* @retval Pointer to the found DHCP lease. +* @retval NULL if not found. +* +*/ struct dhcp_lease *dhcp_find_lease(const struct dhcp_msg *msg, const struct dhcp_option_info *opt_info, struct dhcp_lease **pprev); +/** +* @brief Process received DHCP message and update lease information. +* +* This function validate and process a received DHCP message, find or create/update the associated lease and persist changes. +* +* @param[in] recv_msg - Pointer to the received DHCP message to process. +* @param[in] recv_msg_size - Size of the received DHCP message in bytes. +* @param[in] opt_info - Pointer to DHCP option info containing parsed options from the message. +* @param[in] recv_ifindex - Index of the interface from which the message was received. +* @param[in] recv_iftype - Type of the interface from which the message was received. +* +* @return DHCP lease this messsage associated with +* @retval Pointer to the DHCP lease associated with this message if processing success. +* @retval NULL if processing fails. +* +*/ struct dhcp_lease* dhcp_process_msg(struct dhcp_msg *recv_msg, size_t recv_msg_size, struct dhcp_option_info *opt_info, int recv_ifindex, int recv_iftype); +/** +* @brief Relay DHCP message to the appropriate interface with modified options. +* +* For DHCP OFFER and ACK, this function will update Router option and DNS server option. +* It will also update IP length field, UDP length field, as well as IP checksum field accordingly. +* UDP checksum field will be zero out. (Not necessary in a LAN environment). +* +* @param[in] lease - Pointer to the DHCP lease associated with this message. +* @param[in] recv_packet - Pointer to the received packet buffer including all headers. +* @param[in] udp_header_offset - Offset to the UDP header in the packet buffer in bytes. +* @param[in] recv_msg - Pointer to the received DHCP message. +* @param[in] recv_msg_size - Size of the received DHCP message in bytes. +* @param[in] opt_info - Pointer to DHCP option info containing parsed options. +* +* @return None. +* +*/ void dhcp_relay_message(struct dhcp_lease *lease, void *recv_packet, int udp_header_offset, struct dhcp_msg *recv_msg, size_t recv_msg_size, struct dhcp_option_info *opt_info); +/** +* @brief Encode DHCP option list to buffer, replacing Router and DNS Server options with proxy IP. +* +* This function encode a linked list of DHCP options to a buffer, forcibly replacing Router and DNS Server values with the relay agent's own IP address. +* +* @param[in] option_list - Pointer to the linked list of DHCP options to encode. +* @param[out] buf - Pointer to the buffer where encoded options will be written. +* @param[in] bufsize - Size of the buffer in bytes. +* +* @return The number of bytes written to the buffer. +* +*/ ssize_t dhcp_encode_option_list(const struct dhcp_option *option_list, ui8 *buf, size_t bufsize); #ifdef __cplusplus diff --git a/source/dhcpproxy/dhcp_util.h b/source/dhcpproxy/dhcp_util.h index 03fee8f3..805a50d0 100644 --- a/source/dhcpproxy/dhcp_util.h +++ b/source/dhcpproxy/dhcp_util.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -42,33 +42,164 @@ #include "dhcp_msg.h" +/** +* @brief Send a DHCP message to the specified destination address. +* +* This function transmits the complete DHCP message to the destination. +* +* @param[in] s - Socket descriptor used to send the message. +* @param[in] msg - Pointer to the DHCP message data to send. +* @param[in] size - Size of the DHCP message in bytes. +* @param[in] dest_addr - Destination socket address for the message. +* +* @return None. +* +*/ void dhcp_send(int s, const unsigned char *msg, unsigned int size, struct sockaddr_in dest_addr); +/** +* @brief Insert an ARP record for a host. +* +* This function Insert ARP record, required if DHCP message is unicast to a host that has not finished IP initialization. +* +* @param[in] s - Socket descriptor used for the ioctl operation. +* @param[in] device_name - Pointer to the network device name string. +* @param[in] ip_addr - IP address to add to the ARP table. +* @param[in] htype - Hardware type. +* @param[in] hlen - Hardware address length in bytes. +* @param[in] chaddr - Pointer to the hardware address buffer. +* +* @return None. +* +*/ void insert_arp_record(int s, const char *device_name, struct sockaddr_in ip_addr, ui8 htype, ui8 hlen, ui8* chaddr); +/** +* @brief Create a DHCP socket and bind it to a port and device. +* +* This function opens a socket suitable for DHCP relay/server use and binds it to the given local port and interface. +* +* @param[in] port - Port number to bind the socket to. +* @param[in] device_name - Pointer to the network device name string to bind to. +* \n If NULL, the socket will not be bound to a specific device. +* +* @return The status of the operation. +* @retval The socket descriptor on success. +* @retval -1 on error. +* +*/ int dhcp_create_socket(int port, const char* device_name); +/** +* @brief Receive a packet from a DHCP socket with source and destination IP addresses. +* +* This function uses recvmsg to obtain the packet's destination IP in addition to the source address. +* +* @param[in] s - Socket descriptor to receive from. +* @param[out] buf - Pointer to the buffer to store received data. +* @param[in] len - Size of the buffer in bytes. +* @param[in] flags - Flags for the recvmsg operation. +* @param[out] from - Pointer to store the source address. +* @param[out] to - Pointer to store the destination IP address. +* +* @return The status of operation. +* @retval The number of bytes received on success. +* @retval -1 on error. +* +*/ int dhcp_recvfrom_to(int s, void *buf, size_t len, int flags, struct sockaddr_in *from, struct in_addr *to); +/** +* @brief Dump binary data in hexadecimal and ASCII format for diagnostic purposes. +* +* This function outputs the data in hexadecimal and ASCII format. +* +* @param[in] data - Pointer to the binary data buffer to dump. +* @param[in] size - Size of the data buffer in bytes. +* +* @return None. +* +*/ void dump_data(const unsigned char *data, size_t size); +/** +* @brief Dump binary data in short form showing hexadecimal and ASCII on a single line. +* +* This function displays the data in a short, one-line format suitable for inline logging. +* +* @param[in] data - Pointer to the binary data buffer to dump. +* @param[in] size - Size of the data buffer in bytes. +* +* @return None. +* +*/ void dump_data_short(const unsigned char *data, size_t size); +/** +* @brief Dump MAC address in standard colon-separated hexadecimal format. +* +* @param[in] param - Pointer to the 6-byte MAC address buffer. +* +* @return None. +* +*/ void dump_mac_addr(const void *param); +/** +* @brief Dump IP address in dotted-decimal notation. +* +* @param[in] param - Pointer to the 4-byte IP address buffer. +* +* @return None. +* +*/ void dump_ip_addr(const void *param); +/** +* @brief Dump a list of IP addresses in comma-separated dotted-decimal notation. +* +* @param[in] data - Pointer to the buffer containing IP addresses. +* @param[in] size - Size of the data buffer in bytes. +* +* @return None. +* +*/ void dump_ip_list(const unsigned char *data, size_t size); +/** +* @brief Dump a single DHCP option with formatted output based on option type. +* +* @param[in] p_option - Pointer to the DHCP option to dump. +* +* @return None. +* +*/ void dump_dhcp_option(const struct dhcp_option *p_option); +/** +* @brief Dump a linked list of DHCP options. +* +* @param[in] option_list - Pointer to the first DHCP option in the linked list. +* +* @return None. +* +*/ void dump_dhcp_option_list(const struct dhcp_option *option_list); +/** +* @brief Dump complete DHCP message including header fields and all options. +* +* @param[in] msg - Pointer to the DHCP message to dump. +* @param[in] opts - Pointer to the parsed DHCP option info. +* +* @return None. +* +*/ void dump_dhcp_msg(const struct dhcp_msg *msg, const struct dhcp_option_info *opts); -#endif // _DHCP_UTIL_H_ +#endif // _DHCP_UTIL_H_ \ No newline at end of file diff --git a/source/dhcpproxy/packet_util.h b/source/dhcpproxy/packet_util.h index f8eff214..b74424ec 100644 --- a/source/dhcpproxy/packet_util.h +++ b/source/dhcpproxy/packet_util.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -103,29 +103,112 @@ struct udp_header extern "C" { #endif +/** +* @brief Create a packet socket for raw packet I/O. +* +* @return The status of the operation +* @retval The socket descriptor on success. +* @retval -1 on error. +* +*/ int packet_init_socket(); +/** +* @brief Get the interface index by interface name. +* +* @param[in] device_name - Pointer to the network device name string. +* +* @return Interface index +* @return The interface index on success. +* @retval -1 on error. +* +*/ int get_ifindex(const char *device_name); +/** +* @brief Attach a socket filter to the packet socket. +* +* @param[in] filter - Pointer to the Berkeley Packet Filter (BPF) program array. +* @param[in] filter_len - Number of filter instructions in the filter array. +* +* @return The status of the operation. +* @return 0 on success. +* @retval -1 on error. +* +*/ int packet_attach_filter(struct sock_filter *filter, int filter_len); +/** +* @brief Add an IP interface to the packet socket interface list. +* +* @param[in] ifname - Pointer to the interface name string. +* @param[in] iftype - Interface type, opaque to packet utility. +* +* @return The status of the operation. +* @return 0 on success. +* @retval -1 if too many interfaces or invalid interface. +* +*/ int packet_add_interface(const char *ifname, int iftype); +/** +* @brief Bind the packet socket to IP protocol. +* +* @return The status of the operation. +* @return 0 on success. +* @retval -1 on error. +* +*/ int packet_bind_socket(); +/** +* @brief Receive data from the packet socket. +* +* @param[out] buf - Pointer to the buffer provided by caller to store received data. +* @param[in] len - Size of the buffer in bytes. +* @param[in] flags - Flags for the recvfrom operation. +* @param[out] from_addr - Pointer to store the socket address. +* @param[out] from_intf - Pointer to store the interface from which data was received. +* @param[in] timeout - Pointer to optional timeout value. +* +* @return The size of data +* @retval size if data received successfully +* @retval -1 if error. +* @retval 0 if timeout. +* +*/ int packet_recvfrom(void *buf, size_t len, int flags, struct sockaddr_ll *from_addr, struct packet_intf **from_intf, struct timeval *timeout); +/** +* @brief Send data to the packet socket. +* +* @param[in] ifindex - Interface index of the interface used to send packet. +* @param[in] buf - Pointer to the data buffer to be sent. +* @param[in] len - Size of the data in bytes. +* @param[in] flags - Flags for the sendto operation. +* +* @return The size of data sent. +* @retval The size of data sent on success. +* @retval -1 on error. +* +*/ int packet_sendto(int ifindex, const void *buf, size_t len, int flags); /** - * @brief return IP header - * @param mac_header - * @param size - ethernet packet size - */ +* @brief Get the IP header from an Ethernet packet. +* +* @param[in] mac_header - Pointer to the MAC header of the Ethernet packet. +* @param[in] size - Size of the ethernet packet in bytes. +* +* @return The IP header +* @retval Pointer to the IP header on success. +* @retval NULL if the packet is too small. +* +*/ static inline struct ip_header *get_ip_header(void *mac_header, unsigned int size) { return size < sizeof(struct mac_header)+MIN_IP_HEADER_SIZE ? NULL : @@ -133,18 +216,29 @@ static inline struct ip_header *get_ip_header(void *mac_header, unsigned int siz } /** - * @brief return IP header size - */ +* @brief Get the IP header size including options. +* +* @param[in] iph - Pointer to the IP header. +* +* @return The IP header size in bytes. +* +*/ static inline unsigned int get_ip_header_size(const struct ip_header *iph) { return (iph->vihl&0xf)<<2; } /** - * @brief return IP payload pointer - * @param iph IP header - * @param size of IP packet - */ +* @brief Get the IP payload pointer. +* +* @param[in] iph - Pointer to the IP header. +* @param[in] size - Size of the IP packet in bytes. +* +* @return The IP payload. +* @retval Pointer to the IP payload on success. +* @retval NULL if the header size is invalid. +* +*/ static inline void *get_ip_payload(struct ip_header *iph, unsigned int size) { unsigned int iph_size = get_ip_header_size(iph); @@ -154,10 +248,16 @@ static inline void *get_ip_payload(struct ip_header *iph, unsigned int size) } /** - * @brief return UDP header - * @param ip_hdr IP header - * @param size IP packet size - */ +* @brief Get the UDP header from an IP packet. +* +* @param[in] ip_hdr - Pointer to the IP header. +* @param[in] size - Size of the IP packet in bytes. +* +* @return The UDP header. +* @retval Pointer to the UDP header. +* @retval NULL if the packet is too small. +* +*/ static inline struct udp_header *get_udp_header(void *ip_hdr, unsigned int size) { struct ip_header *iph = (struct ip_header*)ip_hdr; @@ -167,21 +267,32 @@ static inline struct udp_header *get_udp_header(void *ip_hdr, unsigned int size) } /** - * @param iph IP header - * @param size data size starting from IP header - * @return 1 if IP packet is truncated - */ +* @brief Check if the IP packet is truncated. +* +* @param[in] iph - Pointer to the IP header. +* @param[in] size - Data size starting from the IP header in bytes. +* +* @return The truncation status. +* @retval 1 if IP packet is truncated. +* @retval 0 if IP packet is not truncated. +* +*/ static inline int is_packet_truncated(const struct ip_header *iph, unsigned int size) { return size < ntohs(iph->len); } /** - * @param iph IP header - * @param udph UDP header - * @return 1 if it is a fragmented packet or IP packet does not contain - * entire UDP packet - */ +* @brief Check if the IP packet is fragmented or incomplete. +* +* @param[in] iph - Pointer to the IP header. +* @param[in] udph - Pointer to the UDP header. +* +* @return The fragmentation status. +* @retval 1 if it is a fragmented packet or IP packet does not contain entire UDP packet. +* @retval 0 if the packet is not fragmented and complete. +* +*/ static inline int is_ip_fragmented(const struct ip_header *iph, const struct udp_header *udph) { @@ -190,14 +301,33 @@ static inline int is_ip_fragmented(const struct ip_header *iph, } /** - * @brief return UDP payload pointer - * @param udp_hdr UDP header - */ +* @brief Get the UDP payload pointer. +* +* @param[in] udp_hdr - Pointer to the UDP header. +* +* @return Pointer to the UDP payload. +* +*/ static inline void *get_udp_payload(void *udp_hdr) { return udp_hdr + UDP_HEADER_SIZE; } +/** +* @brief Validate and parse an Ethernet packet to extract header pointers. +* +* @param[in] packet - Pointer to the ethernet packet buffer. +* @param[in] size - Size of the ethernet packet in bytes. +* @param[out] machdr - Pointer to store the MAC header. +* @param[out] iphdr - Pointer to store the IP header. +* @param[out] udphdr - Pointer to store the UDP header. +* @param[out] udp_payload_size - Pointer to store the UDP payload size in bytes. +* +* @return The status of the operation. +* @return Pointer to the UDP payload on success. +* @retval NULL if parse/validation fails. +* +*/ void *parse_and_validate_ethernet_packet(void *packet, unsigned int size, struct mac_header **machdr, struct ip_header **iphdr, @@ -208,6 +338,4 @@ void *parse_and_validate_ethernet_packet(void *packet, unsigned int size, } #endif -#endif // _PACKET_UTIL_H_ - - +#endif // _PACKET_UTIL_H_ \ No newline at end of file diff --git a/source/firewall/firewall.h b/source/firewall/firewall.h index 79dd84e2..2d3bc2a4 100644 --- a/source/firewall/firewall.h +++ b/source/firewall/firewall.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -62,9 +62,64 @@ #include "safec_lib_common.h" #include "ansc_status.h" +/** +* @brief Apply logging rules to the filter table. +* +* This function adds iptables/ip6tables rules for logging dropped or rejected packets +* based on the configured firewall level and logging settings. +* +* @param[in] fp - Pointer to the FILE stream for writing filter rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int do_logs(FILE *fp); + +/** +* @brief Apply WAN to self attack protection rules. +* +* Adds protection against common WAN-side attacks targeting the router itself. +* +* @param[in] fp - Pointer to the FILE stream for writing filter rules. +* @param[in] wan_ip - Pointer to the WAN IP address string. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int do_wan2self_attack(FILE *fp,char* wan_ip); + +/** +* @brief Prepare IPv4 firewall rules and write to file. +* +* This function opens the specified file and writes all required iptables rules for IPv4 according to +* current configuration, features and security policies. +* +* @param[in] fw_file - Pointer to the firewall file path string. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval -1 on bad input parameters. +* @retval -2 when could not open firewall file. +* +*/ int prepare_ipv4_firewall(const char *fw_file); + +/** +* @brief Prepare IPv6 firewall rules and write to file. +* +* This function opens the specified file and writes all required iptables rules for IPv6 according to +* current configuration, features and security policies. +* +* @param[in] fw_file - Pointer to the firewall file path string. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval -1 on Bad input parameters. +* @retval -2 when could not open firewall file. +* +*/ int prepare_ipv6_firewall(const char *fw_file); #define CCSP_SUBSYS "eRT." @@ -115,10 +170,40 @@ extern void* bus_handle ; extern int sysevent_fd; extern char sysevent_ip[19]; extern unsigned short sysevent_port; + +/** +* @brief Check if the HOTSPOT interface is currently active. +* +* This function queries the WAN Manager to determine if the HOTSPOT interface is active. +* It retrieves the interface active status parameter which contains a pipe-delimited list +* of WAN interfaces and their statuses in the format: "INTERFACE_NAME,STATUS|INTERFACE_NAME,STATUS|...". +* The function parses this string to check if HOTSPOT is present and has an active status (value = 1). +* Example response: "HOTSPOT,1|WANOE,0|DSL,0" would return true since HOTSPOT has status 1. +* +* @return The status of the HOTSPOT interface. +* @retval true if the HOTSPOT interface is active (status = 1). +* @retval false if the HOTSPOT interface is not active, not present, or if the query fails. +* +*/ bool IsHotspotActive(void); #define TR181_ACTIVE_WAN_INTERFACE "Device.X_RDK_WanManager.InterfaceActiveStatus" -#define PSM_VALUE_GET_STRING(name, str) PSM_Get_Record_Value2(bus_handle, CCSP_SUBSYS, name, NULL, &(str)) +#define PSM_VALUE_GET_STRING(name, str) PSM_Get_Record_Value2(bus_handle, CCSP_SUBSYS, name, NULL, &(str)) +/** +* @brief Get IPv6 addresses for a given interface. +* +* @param[in] ifname - Pointer to the interface name string. +* @param[out] ipArry - Array to store the retrieved IPv6 addresses. +* @param[in,out] p_num - Pointer to the number of addresses. +* \n On input, maximum number of addresses to retrieve. +* \n On output, actual number of addresses retrieved. +* @param[in] scope_in - Scope filter for IPv6 addresses. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval -1 on failure. +* +*/ int get_ip6address (char * ifname, char ipArry[][40], int * p_num, unsigned int scope_in); // Constants used by both files @@ -126,111 +211,737 @@ int get_ip6address (char * ifname, char ipArry[][40], int * p_num, unsigned int #define MAX_LEN_IPV6_INF 32 #endif + // Raw table functions +/** +* @brief Apply raw table rules for Puma7 platform. +* +* @param[in] fp - Pointer to the FILE stream for writing raw table rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int do_raw_table_puma7(FILE *fp); // IPv6 specific functions +/** +* @brief Apply IPv6 source/destination filter rules. +* +* @param[in] fp - Pointer to the FILE stream for writing filter rules. +* +* @return None. +* +*/ void do_ipv6_sn_filter(FILE *fp); + +/** +* @brief Apply IPv6 NAT table rules. +* +* @param[in] fp - Pointer to the FILE stream for writing NAT table rules. +* +* @return None. +* +*/ void do_ipv6_nat_table(FILE *fp); + +/** +* @brief Apply IPv6 filter table rules. +* +* Core IPv6 filter table policy enforcement. +* +* @param[in] fp - Pointer to the FILE stream for writing filter table rules. +* +* @return None. +* +*/ void do_ipv6_filter_table(FILE *fp); + +/** +* @brief Apply IPv6 UI over WAN filter rules. +* +* Controlled by the "UI over WAN" feature flag. +* +* @param[in] fp - Pointer to the FILE stream for writing filter table rules. +* +* @return None. +* +*/ void do_ipv6_UIoverWAN_filter(FILE* fp); -void do_ipv6_filter_table(FILE *fp); + // Access rules +/** +* @brief Apply Ethernet WAN MSO GUI access rules. +* +* @param[in] filter_fp - Pointer to the FILE stream for writing filter table rules. +* @param[in] mangle_fp - Pointer to the FILE stream for writing mangle table rules. +* +* @return None. +* +*/ void ethwan_mso_gui_acess_rules(FILE *filter_fp, FILE *mangle_fp); // Block and protection functions +/** +* @brief Block WPAD (Web Proxy Auto-Discovery) and ISATAP IPv6 traffic. +* +* Prevents known attack vectors related to WPAD spoofing and ISATAP tunneling. +* +* @param[in] fp - Pointer to the FILE stream for writing filter rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int do_wpad_isatap_blockv6(FILE *fp); + +/** +* @brief Block fragmented IPv6 packets. +* +* @param[in] fp - Pointer to the FILE stream for writing filter rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int do_blockfragippktsv6(FILE *fp); + +/** +* @brief Apply IPv6 port scan protection rules. +* +* Function to add IP Table rules against Ports scanning. +* +* @param[in] fp - Pointer to the FILE stream for writing filter rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int do_portscanprotectv6(FILE *fp); + +/** +* @brief Apply IPv6 IP flood detection rules. +* +* Function to add IP Table rules against IPV6 Flooding. +* +* @param[in] fp - Pointer to the FILE stream for writing filter rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int do_ipflooddetectv6(FILE *fp); + +/** +* @brief Block WPAD (Web Proxy Auto-Discovery) and ISATAP IPv4 traffic. +* +* @param[in] fp - Pointer to the FILE stream for writing filter rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int do_wpad_isatap_blockv4 (FILE *fp); + +/** +* @brief Block fragmented IPv4 packets. +* +* @param[in] fp - Pointer to the FILE stream for writing filter rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int do_blockfragippktsv4(FILE *fp); + +/** +* @brief Apply IPv4 port scan protection rules. +* +* Function to add IP Table rules against Ports scanning. +* +* @param[in] fp - Pointer to the FILE stream for writing filter rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int do_portscanprotectv4(FILE *fp); + +/** +* @brief Apply IPv4 IP flood detection rules. +* +* Function to add IP Table rules against IPV4 Flooding. +* +* @param[in] fp - Pointer to the FILE stream for writing filter rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int do_ipflooddetectv4(FILE *fp); + +/** +* @brief Apply web UI attack filter rules. +* +* @param[in] filter_fp - Pointer to the FILE stream for writing filter table rules. +* +* @return None. +* +*/ void do_webui_attack_filter(FILE *filter_fp); + +/** +* @brief Apply WAN/LAN web UI attack protection rules. +* +* @param[in] fp - Pointer to the FILE stream for writing filter rules. +* @param[in] interface - Pointer to the interface name string. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int wan_lan_webui_attack(FILE *fp, const char *interface); // Rule preparation functions +/** +* @brief Prepare RABID rules. +* +* @param[in] filter_fp - Pointer to the FILE stream for writing filter table rules. +* @param[in] mangle_fp - Pointer to the FILE stream for writing mangle table rules. +* @param[in] ver - IP version type. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int prepare_rabid_rules(FILE *filter_fp, FILE *mangle_fp, ip_ver_t ver); + +/** +* @brief Prepare RABID rules version 2020Q3B. +* +* @param[in] filter_fp - Pointer to the FILE stream for writing filter table rules. +* @param[in] mangle_fp - Pointer to the FILE stream for writing mangle table rules. +* @param[in] ver - IP version type. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int prepare_rabid_rules_v2020Q3B(FILE *filter_fp, FILE *mangle_fp, ip_ver_t ver); + +/** +* @brief Prepare RABID rules for MAP-T (Mapping of Address and Port with Translation). +* +* @param[in] filter_fp - Pointer to the FILE stream for writing filter table rules. +* @param[in] ver - IP version type. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int prepare_rabid_rules_for_mapt(FILE *filter_fp, ip_ver_t ver); + +/** +* @brief Apply parental control firewall rules. +* +* @param[in] fp - Pointer to the FILE stream for writing filter rules. +* @param[in] nat_fp - Pointer to the FILE stream for writing NAT table rules. +* @param[in] iptype - IP type. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int do_parental_control(FILE *fp, FILE *nat_fp, int iptype); + +/** +* @brief Prepare LNF internet access rules. +* +* @param[in] mangle_fp - Pointer to the FILE stream for writing mangle table rules. +* @param[in] iptype - IP type. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval -1 on failure. +* +*/ int prepare_lnf_internet_rules(FILE *mangle_fp, int iptype); + +/** +* @brief Allow container traffic through firewall. +* +* @param[in] pFilter - Pointer to the FILE stream for writing filter table rules. +* @param[in] pMangle - Pointer to the FILE stream for writing mangle table rules. +* @param[in] pNat - Pointer to the FILE stream for writing NAT table rules. +* @param[in] family - IP address family. +* +* @return None. +* +*/ void do_container_allow(FILE *pFilter, FILE *pMangle, FILE *pNat, int family); // MAPT related functions +/** +* @brief Apply MAP-T IPv6 filter rules. +* +* The function apply IPv6 Rules for HUB4 MAPT feature. +* +* @param[in] filter_fp - Pointer to the FILE stream for writing filter table rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int do_mapt_rules_v6(FILE *filter_fp); // HUB4 specific functions #ifdef _HUB4_PRODUCT_REQ_ +/** +* @brief Apply HUB4 voice service IPv6 firewall rules. +* +* @param[in] filter_fp - Pointer to the FILE stream for writing filter table rules. +* @param[in] mangle_fp - Pointer to the FILE stream for writing mangle table rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int do_hub4_voice_rules_v6(FILE *filter_fp, FILE *mangle_fp); + +/** +* @brief Apply HUB4 DNS routing IPv6 mangle rules. +* +* @param[in] mangle_fp - Pointer to the FILE stream for writing mangle table rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int do_hub4_dns_rule_v6(FILE *mangle_fp); + #ifdef HUB4_BFD_FEATURE_ENABLED +/** +* @brief Apply HUB4 BFD (Bidirectional Forwarding Detection) IPv6 rules. +* +* @param[in] filter_fp - Pointer to the FILE stream for writing filter table rules. +* @param[in] mangle_fp - Pointer to the FILE stream for writing mangle table rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int do_hub4_bfd_rules_v6(FILE *filter_fp, FILE *mangle_fp); + #endif #ifdef HUB4_QOS_MARK_ENABLED +/** +* @brief Apply QoS (Quality of Service) output marking IPv6 mangle rules. +* +* @param[in] mangle_fp - Pointer to the FILE stream for writing mangle table rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int do_qos_output_marking_v6(FILE *mangle_fp); + #endif #ifdef HUB4_SELFHEAL_FEATURE_ENABLED +/** +* @brief Apply self-heal IPv6 mangle rules. +* +* @param[in] mangle_fp - Pointer to the FILE stream for writing mangle table rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int do_self_heal_rules_v6(FILE *mangle_fp); + #endif #endif // MultiNet related functions #ifdef INTEL_PUMA7 +/** +* @brief Prepare MultiNet IPv6 mangle table rules for Puma7 platform. +* +* @param[in] mangle_fp - Pointer to the FILE stream for writing mangle table rules. +* +* @return None. +* +*/ void prepare_multinet_mangle_v6(FILE *mangle_fp); + #endif #ifdef MULTILAN_FEATURE +/** +* @brief Prepare MultiNet IPv6 filter forward chain rules. +* +* @param[in] fp - Pointer to the FILE stream for writing filter table rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int prepare_multinet_filter_forward_v6(FILE *fp); + +/** +* @brief Prepare MultiNet IPv6 filter output chain rules. +* +* This function prepare the iptables-restore file that establishes all ipv6 firewall rules pertaining to traffic +* which will be either forwarded or received locally. +* +* @param[in] fp - Pointer to the FILE stream for writing filter table rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int prepare_multinet_filter_output_v6(FILE *fp); + #endif // IPv6 rule mode functions #ifdef RDKB_EXTENDER_ENABLED +/** +* @brief Prepare IPv6 firewall rules for extender mode. +* +* @param[in] raw_fp - Pointer to the FILE stream for writing raw table rules. +* @param[in] mangle_fp - Pointer to the FILE stream for writing mangle table rules. +* @param[in] nat_fp - Pointer to the FILE stream for writing NAT table rules. +* @param[in] filter_fp - Pointer to the FILE stream for writing filter table rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int prepare_ipv6_rule_ex_mode(FILE *raw_fp, FILE *mangle_fp, FILE *nat_fp, FILE *filter_fp); #endif #if defined(CISCO_CONFIG_DHCPV6_PREFIX_DELEGATION) && !defined(_CBR_PRODUCT_REQ_) +/** +* @brief Prepare IPv6 MultiNet rules with DHCPv6 prefix delegation support. +* +* @param[in] fp - Pointer to the FILE stream for writing filter table rules. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval -1 on failure. +* +*/ int prepare_ipv6_multinet(FILE *fp); + #endif // Access control functions +/** +* @brief Apply LAN telnet and SSH access rules. +* +* This function enable / disable telnet and ssh from lan side. +* +* @param[in] fp - Pointer to the FILE stream for writing filter rules. +* @param[in] family - IP address family. +* \n Possible values are AF_INET for IPv4 or AF_INET6 for IPv6. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int lan_telnet_ssh(FILE *fp, int family); + +/** +* @brief Apply SSH IP access table whitelist rules. +* +* @param[in] fp - Pointer to the FILE stream for writing filter rules. +* @param[in] port - Pointer to the SSH port number string. +* @param[in] family - IP address family. +* \n Possible values are AF_INET for IPv4 or AF_INET6 for IPv6. +* @param[in] interface - Pointer to the interface name string. +* +* @return None. +* +*/ void do_ssh_IpAccessTable(FILE *fp, const char *port, int family, const char *interface); + +/** +* @brief Apply SNMP IP access table whitelist rules. +* +* @param[in] fp - Pointer to the FILE stream for writing filter rules. +* @param[in] family - IP address family. +* +* @return None. +* +*/ void do_snmp_IpAccessTable(FILE *fp, int family); + +/** +* @brief Apply TR-069 ACS (Auto Configuration Server) whitelist rules. +* +* @param[in] fp - Pointer to the FILE stream for writing filter rules. +* @param[in] family - IP address family. +* +* @return None. +* +*/ void do_tr69_whitelistTable(FILE *fp, int family); + +/** +* @brief Apply remote access control rules. +* +* @param[in] nat_fp - Pointer to the FILE stream for writing NAT table rules. +* @param[in] filter_fp - Pointer to the FILE stream for writing filter table rules. +* @param[in] family - IP address family. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int do_remote_access_control(FILE *nat_fp, FILE *filter_fp, int family); // Port functions +/** +* @brief Apply blocked ports rules. +* +* @param[in] filter_fp - Pointer to the FILE stream for writing filter table rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int do_block_ports(FILE *filter_fp); + +/** +* @brief Apply web UI rate limiting rules to prevent brute force attacks. +* +* This function create chain to ratelimit remote management GUI packets over erouter interface. +* +* @param[in] filter_fp - Pointer to the FILE stream for writing filter table rules. +* +* @return None. +* +*/ void do_webui_rate_limit(FILE *filter_fp); + +/** +* @brief Set LAN access protocol rules. +* +* @param[in] fp - Pointer to the FILE stream for writing filter rules. +* @param[in] port - Pointer to the port number string. +* @param[in] interface - Pointer to the interface name string. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int lan_access_set_proto(FILE *fp, const char *port, const char *interface); + +/** +* @brief Apply single port forwarding rules. +* +* This function prepare the iptables-restore statements for single port forwarding. +* +* @param[in] nat_fp - Pointer to the FILE stream for writing NAT table rules. +* @param[in] filter_fp - Pointer to the FILE stream for writing filter table rules. +* @param[in] iptype - IP type. +* @param[in] filter_fp_v6 - Pointer to the FILE stream for writing IPv6 filter table rules. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval -1 on bad input parameter. +* +*/ int do_single_port_forwarding(FILE *nat_fp, FILE *filter_fp, int iptype, FILE *filter_fp_v6); + +/** +* @brief Apply port range forwarding rules. +* +* @param[in] nat_fp - Pointer to the FILE stream for writing NAT table rules. +* @param[in] filter_fp - Pointer to the FILE stream for writing filter table rules. +* @param[in] iptype - IP type. +* @param[in] filter_fp_v6 - Pointer to the FILE stream for writing IPv6 filter table rules. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval -1 on bad input parameter. +* +*/ int do_port_range_forwarding(FILE *nat_fp, FILE *filter_fp, int iptype, FILE *filter_fp_v6); + +/** +* @brief Open special ports from WAN to self or LAN. +* +* @param[in] fp - Pointer to the FILE stream for writing filter rules. +* +* @return None. +* +*/ void do_openPorts(FILE *fp); + +/** +* @brief Forward special ports from WAN to self or LAN. +* +* @param[in] fp - Pointer to the FILE stream for writing NAT table rules. +* +* @return None. +* +*/ void do_forwardPorts(FILE *fp); // Utility functions +/** +* @brief Validate IPv6 address format. +* +* @param[in] ip_addr_string - Pointer to the IPv6 address string to validate. +* +* @return The validation status. +* @retval 1 if the IPv6 address is valid. +* @retval 0 if the IPv6 address is invalid. +* +*/ int IsValidIPv6Addr(char* ip_addr_string); + +/** +* @brief Check if ULA (Unique Local Address) is enabled. +* +*This function check if ULA is enabled, If ULA is enabled we will broadcast ULA prefix. +* +* @return The ULA enabled status. +* @retval 0 if ULA is enabled. +* @retval -1 if ULA is disabled. +* +*/ int checkIfULAEnabled(void); + +/** +* @brief Get parameter values from the RDK bus. +* +* This function retrieves a parameter value from the specified component on the RDK bus +* using the CcspBaseIf_getParameterValues interface. The returned value is copied to the +* provided buffer with proper null-termination and truncation handling. +* +* @param[in] pComponent - Pointer to the component name string. +* @param[in] pBus - Pointer to the D-Bus path string . +* @param[in] pParamName - Pointer to the parameter name to query. +* @param[out] pReturnVal - Pointer to a buffer where the parameter value will be returned. +* The buffer must be pre-allocated by the caller with sufficient size. +* @param[in] returnValSize - Size of the pReturnVal buffer in bytes. Must be greater than 0. +* The returned string will be null-terminated and truncated if necessary +* to fit within this size. +* +* @return The status of the operation. +* @retval ANSC_STATUS_SUCCESS if the parameter value is successfully retrieved and copied. +* @retval ANSC_STATUS_FAILURE if pReturnVal is NULL, returnValSize is 0, or the RDK bus query fails. +* +*/ ANSC_STATUS RdkBus_GetParamValues(char *pComponent,char *pBus,char *pParamName,char *pReturnVal,size_t returnValSize); +/** +* @brief Get list of IPv6 interfaces. +* +* This function used to get the list of IPv6 interfaces. +* +* @param[out] Interface - Array to store IPv6 interface names. +* @param[in,out] len - Pointer to the number of interfaces. +* \n On input, maximum number of interfaces to retrieve. +* \n On output, actual number of interfaces retrieved. +* +* @return None. +* +*/ void getIpv6Interfaces(char Interface[MAX_NO_IPV6_INF][MAX_LEN_IPV6_INF], int *len); + +/** +* @brief Prepare hotspot GRE (Generic Routing Encapsulation) IPv6 rules. +* +* @param[in] filter_fp - Pointer to the FILE stream for writing filter table rules. +* +* @return None. +* +*/ void prepare_hotspot_gre_ipv6_rule(FILE *filter_fp); + +/** +* @brief Apply LAN to self rules based on WAN IPv6 address. +* +* @param[in] filter_fp - Pointer to the FILE stream for writing filter table rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int do_lan2self_by_wanip6(FILE *filter_fp); + +/** +* @brief Open video analytics port in firewall rules. +* +* @param[in] fp - Pointer to the FILE stream for writing filter rules. +* +* @return None. +* +*/ void do_OpenVideoAnalyticsPort(FILE *fp); + +/** +* @brief Check if firewall service is needed. +* +* @return The service needed status. +* @retval true if service is needed. +* @retval false if service is not needed. +* +*/ bool isServiceNeeded(void); + // DNS functions #ifdef XDNS_ENABLE +/** +* @brief Apply DNS routing rules for XDNS (Extended DNS). +* +* This function route DNS requests from LAN through dnsmasq. +* +* @param[in] nat_fp - Pointer to the FILE stream for writing NAT table rules. +* @param[in] iptype - IP type. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int do_dns_route(FILE *nat_fp, int iptype); + #endif // Speedboost functions #if defined(SPEED_BOOST_SUPPORTED) && defined(SPEED_BOOST_SUPPORTED_V6) +/** +* @brief Apply speed boost port marking and redirection rules. +* +* @param[in] mangle_fp - Pointer to the FILE stream for writing mangle table rules. +* @param[in] nat_fp - Pointer to the FILE stream for writing NAT table rules. +* @param[in] iptype - IP type. +* \n Value 4 for IPv4 or 6 for IPv6. +* +* @return None. +* +*/ void do_speedboost_port_rules(FILE *mangle_fp, FILE *nat_fp, int iptype); + #endif // String manipulation utilities +/** +* @brief Perform string substitutions in firewall rule strings. +* +* This function change well-known symbols in a string to the running/configured values. +* +* @param[in] in_str - Pointer to the input string. +* @param[out] out_str - Pointer to the output string buffer. +* @param[in] size - Size of the output buffer in bytes. +* +* @return Pointer to the output string. +* @retval A pointer to the output string on success. +* @retval NULL on failure. +* +*/ char *make_substitutions(char *in_str, char *out_str, const int size); // Global variables used in both files @@ -292,7 +1003,17 @@ extern char speedboostportsv6[32]; #ifdef WAN_FAILOVER_SUPPORTED #if !defined(_PLATFORM_RASPBERRYPI_) && !defined(_PLATFORM_BANANAPI_R4_) +/** +* @brief Redirect DNS queries to extender interface in WAN failover mode. +* +* @param[in] nat_fp - Pointer to the FILE stream for writing NAT table rules. +* @param[in] family - IP address family. +* +* @return None. +* +*/ void redirect_dns_to_extender(FILE *nat_fp,int family); + #endif //_PLATFORM_RASPBERRYPI_ && _PLATFORM_BANANAPI_R4_ typedef enum { @@ -301,8 +1022,28 @@ typedef enum { } Dev_Mode; +/** +* @brief Get the device operating mode. +* +* This function used to get device mode. +* +* @return The device mode. +* @retval ROUTER if device is in router mode. +* @retval EXTENDER_MODE if device is in extender mode. +* +*/ unsigned int Get_Device_Mode() ; +/** +* @brief Get the IP address of a specified interface. +* +* @param[in] iface_name - Pointer to the interface name string. +* +* @return The status of the operation or pointer to the IP address string. +* @retval Pointer to the IP address string on success. +* @retval NULL on failure. +* +*/ char* get_iface_ipaddr(const char* iface_name); @@ -320,16 +1061,89 @@ char* get_iface_ipaddr(const char* iface_name); #endif #ifdef RDKB_EXTENDER_ENABLED +/** +* @brief Add interface MSS (Maximum Segment Size) clamping rules. +* +* @param[in] mangle_fp - Pointer to the FILE stream for writing mangle table rules. +* @param[in] family - IP address family. +* +* @return None. +* +*/ void add_if_mss_clamping(FILE *mangle_fp,int family); + +/** +* @brief Start firewall service in extender mode. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval <0 on error code. +* +*/ int service_start_ext_mode () ; +/** +* @brief Prepare IPv4 firewall rules for extender mode. +* +* @param[in] raw_fp - Pointer to the FILE stream for writing raw table rules. +* @param[in] mangle_fp - Pointer to the FILE stream for writing mangle table rules. +* @param[in] nat_fp - Pointer to the FILE stream for writing NAT table rules. +* @param[in] filter_fp - Pointer to the FILE stream for writing filter table rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int prepare_ipv4_rule_ex_mode(FILE *raw_fp, FILE *mangle_fp, FILE *nat_fp, FILE *filter_fp); + +/** +* @brief Prepare IPv6 firewall rules for extender mode. +* +* @param[in] raw_fp - Pointer to the FILE stream for writing raw table rules. +* @param[in] mangle_fp - Pointer to the FILE stream for writing mangle table rules. +* @param[in] nat_fp - Pointer to the FILE stream for writing NAT table rules. +* @param[in] filter_fp - Pointer to the FILE stream for writing filter table rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int prepare_ipv6_rule_ex_mode(FILE *raw_fp, FILE *mangle_fp, FILE *nat_fp, FILE *filter_fp); + +/** +* @brief Check if the device is running in extender profile. +* +* @return The extender profile status. +* @retval 0 if device is in extender profile. +* @retval -1 if device is not in extender profile. +* +*/ int isExtProfile(); + #endif #if defined (WIFI_MANAGE_SUPPORTED) +/** +* @brief Update managed WiFi firewall rules. +* +* @param[in] busHandle - Pointer to the bus handle. +* @param[in] pCurWanInterface - Pointer to the current WAN interface name string. +* @param[in] filterFp - Pointer to the FILE stream for writing filter table rules. +* +* @return None. +* +*/ void updateManageWiFiRules(void * busHandle, char * pCurWanInterface, FILE * filterFp); + +/** +* @brief Check if managed WiFi is enabled. +* +* @return The managed WiFi enabled status. +* @retval true if managed WiFi is enabled. +* @retval false if managed WiFi is disabled. +* +*/ bool isManageWiFiEnabled(void); + #endif/*WIFI_MANAGE_SUPPORTED*/ #if defined (AMENITIES_NETWORK_ENABLED) @@ -337,7 +1151,18 @@ bool isManageWiFiEnabled(void); #define VAP_NAME_2G_INDEX "dmsb.MultiLAN.AmenityNetwork_2g_l3net" #define VAP_NAME_5G_INDEX "dmsb.MultiLAN.AmenityNetwork_5g_l3net" #define VAP_NAME_6G_INDEX "dmsb.MultiLAN.AmenityNetwork_6g_l3net" +/** +* @brief Update amenity network firewall rules. +* +* @param[in] filter_fp - Pointer to the FILE stream for writing filter table rules. +* @param[in] mangle_fp - Pointer to the FILE stream for writing mangle table rules. +* @param[in] iptype - IP type. +* +* @return None. +* +*/ void updateAmenityNetworkRules(FILE *filter_fp , FILE *mangle_fp,int iptype); + #endif /*AMENITIES_NETWORK_ENABLED*/ @@ -348,11 +1173,26 @@ extern int mesh_wan_ipv6_num; extern char mesh_wan_ipv6addr[IF_IPV6ADDR_MAX][40]; extern char dev_type[20]; extern char mesh_wan_ifname[32]; +/** +* @brief Apply hotspot post-routing NAT rules for source address translation. +* +* This function writes iptables post-routing rules to enable Source NAT (SNAT) for hotspot WAN traffic. +* It configures SNAT rules to translate outgoing traffic on the hotspot WAN interface to use the WAN IP address. +* +* @param[in] fp - Pointer to an open file stream where the iptables rules will be written. +* @param[in] isIpv4 - Boolean flag indicating the IP version. +* \n true: Apply IPv4 post-routing rules. +* \n false: Apply IPv6 post-routing rules. +* +* @return None. +* +*/ void applyHotspotPostRoutingRules(FILE *fp, bool isIpv4); #endif #define BUFLEN_256 256 #define FIREWALL_DBUS_PATH "/com/cisco/spvtg/ccsp/wanmanager" #define FIREWALL_COMPONENT_NAME "eRT.com.cisco.spvtg.ccsp.wanmanager" + extern char hotspot_wan_ifname[50]; extern int current_wan_ipv6_num; extern char default_wan_ifname[50]; // name of the regular wan interface @@ -375,8 +1215,26 @@ extern int numifs; /*----*/ #if defined(_WNXL11BWL_PRODUCT_REQ_) +/** +* @brief Apply DNS proxy rules. +* +* @param[in] nat_fp - Pointer to the FILE stream for writing NAT table rules. +* @param[in] family - IP address family. +* +* @return None. +* +*/ void proxy_dns(FILE *nat_fp,int family); +/** +* @brief Get ULA (Unique Local Address) IPv6 address of an interface. +* +* @param[in] ifname - Pointer to the interface name string. +* @param[out] ipaddr - Pointer to the buffer to store the IPv6 address. +* @param[in] max_ip_size - Maximum size of the IP address buffer in bytes. +* +* @return None. +* +*/ void get_iface_ipaddr_ula(const char* ifname,char* ipaddr, int max_ip_size); #endif - diff --git a/source/firewall/firewall_custom.h b/source/firewall/firewall_custom.h index 072384a4..5a7fa670 100644 --- a/source/firewall/firewall_custom.h +++ b/source/firewall/firewall_custom.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -46,49 +46,409 @@ extern FILE *firewallfp; #define FW_DEBUG 1 +/** +* @brief Append device-based packet processing disabled rule. +* +* @param[in] fp - Pointer to the FILE stream for writing firewall rules. +* @param[in] ins_num - Pointer to the instance number string. +* @param[in] lan_ifname - Pointer to the LAN interface name string. +* @param[in] query - Pointer to the MAC address query string. +* +* @return None. +* +*/ void do_device_based_pp_disabled_appendrule(FILE *fp, const char *ins_num, const char *lan_ifname, const char *query); + +/** +* @brief Append device-based packet processing disabled IP rule. +* +* @param[in] fp - Pointer to the FILE stream for writing firewall rules. +* @param[in] ins_num - Pointer to the instance number string. +* @param[in] ipAddr - Pointer to the IP address string. +* +* @return None. +* +*/ void do_device_based_pp_disabled_ip_appendrule(FILE *fp, const char *ins_num, const char *ipAddr); + +/** +* @brief Append parental control management LAN to WAN PC site rule. +* +* @param[in] fp - Pointer to the FILE stream for writing firewall rules. +* +* @return The number of rules appended. +* +*/ int do_parcon_mgmt_lan2wan_pc_site_appendrule(FILE *fp); + +/** +* @brief Insert parental control management LAN to WAN PC site rule at specified index. +* +* @param[in] fp - Pointer to the FILE stream for writing firewall rules. +* @param[in] index - Index position where the rule should be inserted. +* @param[in] nstdPort - Pointer to the non-standard port string. +* +* @return None. +* +*/ void do_parcon_mgmt_lan2wan_pc_site_insertrule(FILE *fp, int index, char *nstdPort); + +/** +* @brief Log firewall messages with variable arguments. +* +* This function logs a message to the firewall log file with a timestamp prefix. +* +* @param[in] fmt - Pointer to the format string for the log message. +* @param[in] ... - Variable arguments for the format string. +* +* @return None. +* +*/ void firewall_log( char* fmt, ...); + +/** +* @brief Update RABID (Router Advertisement Basic Interface Discovery) features status. +* +* @return None. +* +*/ void update_rabid_features_status(); + +/** +* @brief Apply port forwarding rules to the filter table. +* +* @param[in] filter_fp - Pointer to the FILE stream for writing filter table rules. +* +* @return None. +* +*/ void do_forwardPorts(FILE *filter_fp); + +/** +* @brief Apply SNMP IP access table rules. +* +* @param[in] filt_fp - Pointer to the FILE stream for writing filter rules. +* @param[in] family - IP address family. +* +* @return None. +* +*/ void do_snmp_IpAccessTable(FILE *filt_fp, int family); + +/** +* @brief Apply SSH IP access table rules. +* +* @param[in] filt_fp - Pointer to the FILE stream for writing filter rules. +* @param[in] port - Pointer to the SSH port string. +* @param[in] family - IP address family. +* @param[in] interface - Pointer to the interface name string. +* +* @return None. +* +*/ void do_ssh_IpAccessTable(FILE *filt_fp, const char *port, int family, const char *interface); + +/** +* @brief Apply TR-069 whitelist table rules. +* +* @param[in] filt_fp - Pointer to the FILE stream for writing filter rules. +* @param[in] family - IP address family. +* \n Possible values are AF_INET for IPv4 or AF_INET6 for IPv6. +* +* @return None. +* +*/ void do_tr69_whitelistTable(FILE *filt_fp, int family); + +/** +* @brief Apply port mapping filter rules. +* +* This function enable portmap traffic only on loopback and PEER IP. +* +* @param[in] filt_fp - Pointer to the FILE stream for writing filter rules. +* +* @return None. +* +*/ void filterPortMap(FILE *filt_fp); + +/** +* @brief Apply open ports firewall rules. +* +* This function open special ports from wan to self/lan. +* +* @param[in] filter_fp - Pointer to the FILE stream for writing filter table rules. +* +* @return None. +* +*/ void do_openPorts(FILE *filter_fp); + +/** +* @brief Prepare XCONF (external configuration) mangle rules. +* +* @param[in] mangle_fp - Pointer to the FILE stream for writing mangle table rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int prepare_xconf_rules(FILE *mangle_fp); + +/** +* @brief Apply IPv6 self-heal mangle rules. +* +* @param[in] mangle_fp - Pointer to the FILE stream for writing mangle table rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int do_self_heal_rules_v6(FILE *mangle_fp); + +/** +* @brief Apply IPv6 QoS output marking mangle rules. +* +* @param[in] mangle_fp - Pointer to the FILE stream for writing mangle table rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int do_qos_output_marking_v6(FILE *mangle_fp); + +/** +* @brief Apply HUB4 MAP-T IPv6 filter rules. +* +* @param[in] filter_fp - Pointer to the FILE stream for writing filter table rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int do_hub4_mapt_rules_v6(FILE *filter_fp); + +/** +* @brief Apply HUB4 BFD (Bidirectional Forwarding Detection) IPv6 rules. +* +* @param[in] filter_fp - Pointer to the FILE stream for writing filter table rules. +* @param[in] mangle_fp - Pointer to the FILE stream for writing mangle table rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int do_hub4_bfd_rules_v6(FILE *filter_fp, FILE *mangle_fp); + +/** +* @brief Apply HUB4 DNS IPv6 mangle rules. +* +* @param[in] mangle_fp - Pointer to the FILE stream for writing mangle table rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int do_hub4_dns_rule_v6(FILE* mangle_fp); + +/** +* @brief Apply HUB4 voice IPv6 rules. +* +* @param[in] filter_fp - Pointer to the FILE stream for writing filter table rules. +* @param[in] mangle_fp - Pointer to the FILE stream for writing mangle table rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int do_hub4_voice_rules_v6(FILE *filter_fp, FILE *mangle_fp); + +/** +* @brief Apply IPv4 self-heal mangle rules. +* +* @param[in] mangle_fp - Pointer to the FILE stream for writing mangle table rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int do_self_heal_rules_v4(FILE *mangle_fp); + +/** +* @brief Apply IPv4 QoS output marking mangle rules. +* +* @param[in] mangle_fp - Pointer to the FILE stream for writing mangle table rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int do_qos_output_marking_v4(FILE *mangle_fp); + +/** +* @brief Apply HUB4 MAP-T IPv4 rules. +* +* @param[in] nat_fp - Pointer to the FILE stream for writing NAT table rules. +* @param[in] filter_fp - Pointer to the FILE stream for writing filter table rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int do_hub4_mapt_rules_v4(FILE *nat_fp, FILE *filter_fp); + +/** +* @brief Apply HUB4 BFD (Bidirectional Forwarding Detection) IPv4 rules. +* +* @param[in] nat_fp - Pointer to the FILE stream for writing NAT table rules. +* @param[in] filter_fp - Pointer to the FILE stream for writing filter table rules. +* @param[in] mangle_fp - Pointer to the FILE stream for writing mangle table rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int do_hub4_bfd_rules_v4(FILE *nat_fp, FILE *filter_fp, FILE *mangle_fp); + +/** +* @brief Apply HUB4 voice IPv4 filter rules. +* +* @param[in] filter_fp - Pointer to the FILE stream for writing filter table rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int do_hub4_voice_rules_v4(FILE *filter_fp); + +/** +* @brief Check if the system is in self-heal mode. +* +* @return The self-heal mode status. +* @retval 1 if in self-heal mode. +* @retval 0 if not in self-heal mode. +* +*/ int isInSelfHealMode (); + +/** +* @brief Get the LAN IP address. +* +* @return Pointer to the LAN IP address string. +* @retval LAN IP address on success. +* @retval NULL on failure. +* +*/ char *get_lan_ipaddr(); + +/** +* @brief Get the current WAN interface name. +* +* @return Pointer to the current WAN interface name string. +* @retval WAN interface name on success. +* @retval NULL on failure. +* +*/ char *get_current_wan_ifname(); + +/** +* @brief Apply Ethernet WAN MSO GUI access rules. +* +* @param[in] filter_fp - Pointer to the FILE stream for writing filter table rules. +* @param[in] mangle_fp - Pointer to the FILE stream for writing mangle table rules. +* +* @return None. +* +*/ void ethwan_mso_gui_acess_rules(FILE *filter_fp,FILE *mangle_fp); + +/** +* @brief Open video analytics port in firewall rules. +* +* @param[in] filter_fp - Pointer to the FILE stream for writing filter table rules. +* +* @return None. +* +*/ void do_OpenVideoAnalyticsPort (FILE *filter_fp); + +/** +* @brief Apply web UI rate limiting rules. +* +* This function create chain to ratelimit remote management GUI packets over erouter interface. +* +* @param[in] filter_fp - Pointer to the FILE stream for writing filter table rules. +* +* @return None. +* +*/ void do_webui_rate_limit (FILE *filter_fp); + +/** +* @brief Prepare DSCP (Differentiated Services Code Point) rules for prioritized clients. +* +* @param[in] mangle_fp - Pointer to the FILE stream for writing mangle table rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int prepare_dscp_rules_to_prioritized_clnt(FILE* mangle_fp); + +/** +* @brief Prepare LLD (Link Layer Discovery) DSCP rules. +* +* @param[in] mangle_fp - Pointer to the FILE stream for writing mangle table rules. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int prepare_lld_dscp_rules(FILE *mangle_fp); + +/** +* @brief Prepare DSCP rule for host management traffic. +* +* @param[in] mangle_fp - Pointer to the FILE stream for writing mangle table rules. +* +* @return None. +* +*/ void prepare_dscp_rule_for_host_mngt_traffic(FILE *mangle_fp); #if defined(SPEED_BOOST_SUPPORTED) +/** +* @brief Apply speed boost port rules. +* +* @param[in] mangle_fp - Pointer to the FILE stream for writing mangle table rules. +* @param[in] nat_fp - Pointer to the FILE stream for writing NAT table rules. +* @param[in] iptype - IP type. +* +* @return None. +* +*/ void do_speedboost_port_rules(FILE *mangle_fp, FILE *nat_fp , int iptype); + +/** +* @brief Check if a port overlaps with speed boost port range. +* +* @param[in] ExternalPort - External port number. +* @param[in] ExternalPortEndRange - External port end range number. +* @param[in] InternalPort - Internal port number. +* @param[in] InternalPortend - Internal port end range number. +* +* @return The overlap status. +* @retval 1 if there is overlap. +* @retval 0 if there is no overlap. +* +*/ int IsPortOverlapWithSpeedboostPortRange(int ExternalPort, int ExternalPortEndRange, int InternalPort , int InternalPortend); #endif #ifdef FW_DEBUG #define COMMA , #define FIREWALL_DEBUG(x) firewall_log(x); -#else +#else #define FIREWALL_DEBUG(x) #endif @@ -100,16 +460,34 @@ typedef enum { }ip_ver_t; typedef struct fw_shm_mutex { - pthread_mutex_t *ptr; - int fw_shm_create; - int fw_shm_fd; - char fw_mutex[32]; + pthread_mutex_t *ptr; + int fw_shm_create; + int fw_shm_fd; + char fw_mutex[32]; } fw_shm_mutex; +/** +* @brief Initialize a firewall shared memory mutex. +* +* @param[in] name - Pointer to the mutex name string. +* +* @return The initialized firewall shared memory mutex structure. +* +*/ fw_shm_mutex fw_shm_mutex_init(char *name); +/** +* @brief Close a firewall shared memory mutex. +* +* @param[in] mutex - The firewall shared memory mutex structure to close. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval -1 on failure. +* +*/ int fw_shm_mutex_close(fw_shm_mutex mutex); /* diff --git a/source/firewall/firewall_ipv6.c b/source/firewall/firewall_ipv6.c index 5c7a8ade..6dddacdf 100644 --- a/source/firewall/firewall_ipv6.c +++ b/source/firewall/firewall_ipv6.c @@ -1183,7 +1183,7 @@ void do_ipv6_filter_table(FILE *fp){ fprintf(fp, "-A INPUT -i brlan4 -j ACCEPT \n"); fprintf(fp, "-A INPUT -i brlan5 -j ACCEPT \n"); fprintf(fp, "-A INPUT -i brpublic -j ACCEPT \n"); -#if defined (_XB8_PRODUCT_REQ_) && defined(RDK_ONEWIFI) +#if (defined (_XB8_PRODUCT_REQ_) || defined (_SCXF11BFL_PRODUCT_REQ_)) && defined(RDK_ONEWIFI) fprintf(fp, "-A INPUT -i bropen6g -j ACCEPT \n"); fprintf(fp, "-A INPUT -i brsecure6g -j ACCEPT \n"); #endif @@ -1210,7 +1210,7 @@ void do_ipv6_filter_table(FILE *fp){ fprintf(fp, "-A FORWARD -i brlan4 -o brlan4 -j ACCEPT\n"); fprintf(fp, "-A FORWARD -i brlan5 -o brlan5 -j ACCEPT\n"); fprintf(fp, "-A FORWARD -i brpublic -o brpublic -j ACCEPT\n"); -#if defined (_XB8_PRODUCT_REQ_) && defined(RDK_ONEWIFI) +#if (defined (_XB8_PRODUCT_REQ_) || defined (_SCXF11BFL_PRODUCT_REQ_)) && defined(RDK_ONEWIFI) fprintf(fp, "-A FORWARD -i bropen6g -o bropen6g -j ACCEPT\n"); fprintf(fp, "-A FORWARD -i brsecure6g -o brsecure6g -j ACCEPT\n"); #endif diff --git a/source/igd/src/inc/igd_action_port_mapping.h b/source/igd/src/inc/igd_action_port_mapping.h index 4b78601d..295df34e 100644 --- a/source/igd/src/inc/igd_action_port_mapping.h +++ b/source/igd/src/inc/igd_action_port_mapping.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -33,7 +33,7 @@ limitations under the License. **********************************************************************/ -/* +/* * FileName: igd_action_port_mapping.h * Author: Lipin Zhou(zlipin@cisco.com) * Date: 2009-04-30 @@ -56,7 +56,7 @@ * * **/ - + #ifndef _IGD_ACTION_PORT_MAPPING_ #define _IGD_ACTION_PORT_MAPPING_ @@ -74,7 +74,7 @@ typedef struct _genPortMapIndex{ PAL_XML2S_FDMSK fieldMask; - + #define MASK_OF_PORTMAP_INDEX 0x00000001 UINT16 portMapIndex; @@ -82,11 +82,11 @@ typedef struct _genPortMapIndex{ typedef struct _PORT_MAP_INDEX{ PAL_XML2S_FDMSK fieldMask; - + #define MASK_OF_INDEX_REMOTE_HOST 0x00000001 #define MASK_OF_INDEX_EXTERNAL_PORT 0x00000002 #define MASK_OF_INDEX_PROTOCOL 0x00000004 - + CHAR *remoteHost; UINT16 externalPort; CHAR *pmProtocol; @@ -94,7 +94,7 @@ typedef struct _PORT_MAP_INDEX{ typedef struct _PORT_MAP_ENTRY{ PAL_XML2S_FDMSK fieldMask; - + #define MASK_OF_ENTRY_REMOTE_HOST 0x00000001 #define MASK_OF_ENTRY_EXTERNAL_PORT 0x00000002 #define MASK_OF_ENTRY_PROTOCOL 0x00000004 @@ -103,7 +103,7 @@ typedef struct _PORT_MAP_ENTRY{ #define MASK_OF_ENTRY_ENABLED 0x00000020 #define MASK_OF_ENTRY_DESCRIPTION 0x00000040 #define MASK_OF_ENTRY_LEASE_TIME 0x00000080 - + CHAR *remoteHost; UINT16 externalPort; CHAR *pmProtocol; @@ -119,93 +119,126 @@ typedef struct _PORT_MAP_ENTRY{ /***************************interface function***************************/ - /************************************************************ - * Function: IGD_get_NATRSIP_status - * - * Parameters: - * event: INOUT. action request from upnp template - * - * Description: - * This function process the action "IGD_get_NATRSIP_status". - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ +/** +* @brief Get NAT and RSIP status. +* +* Retrieves the NAT (Network Address Translation) and RSIP (Realm-Specific IP) status +* \n for the WAN connection device and returns the values in UPnP action response. +* +* @param[in,out] event - Pointer to action_event structure containing UPnP action request. +* \n The event structure includes service information, request parameters, +* \n and will be populated with response data or error codes. +* +* @return The status of the operation. +* @retval PAL_UPNP_E_SUCCESS if successful. +* @retval IGD_GENERAL_ERROR if input parameter is NULL. +* @retval PAL_UPNP_SOAP_E_ACTION_FAILED if service private data is NULL or PII function fails. +* +*/ INT32 IGD_get_NATRSIP_status(INOUT struct action_event *event); - /************************************************************ - * Function: IGD_get_GenericPortMapping_entry - * - * Parameters: - * event: INOUT. action request from upnp template - * - * Description: - * This function process the action "IGD_get_GenericPortMapping_entry". - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ +/** +* @brief Get generic port mapping entry by index. +* +* Retrieves port mapping entry information by index number. +* \n Returns all port mapping fields including remote host, external/internal ports, +* \n protocol, internal client, enabled status, description, and lease duration. +* \n Input parameter NewPortMappingIndex specifies the entry to retrieve. +* +* @param[in,out] event - Pointer to action_event structure containing UPnP action request. +* \n Input: NewPortMappingIndex (UINT16) - Index of port mapping entry to retrieve. +* \n Output: All port mapping entry fields in action response. +* +* @return The status of the operation. +* @retval PAL_UPNP_E_SUCCESS if successful. +* @retval IGD_GENERAL_ERROR if input parameter is NULL. +* @retval PAL_UPNP_SOAP_E_ACTION_FAILED if service private data is NULL. +* @retval PAL_UPNP_SOAP_E_INVALID_ARGS if XML parsing fails. +* @retval ARRAY_INDEX_INVALID if port mapping index is out of range. +* +*/ INT32 IGD_get_GenericPortMapping_entry(INOUT struct action_event *event); - /************************************************************ - * Function: IGD_get_SpecificPortMapping_entry - * - * Parameters: - * event: INOUT. action request from upnp template - * - * Description: - * This function process the action "IGD_get_SpecificPortMapping_entry". - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ +/** +* @brief Get specific port mapping entry by key fields. +* +* Retrieves port mapping entry information by specifying remote host, external port, and protocol. +* \n Returns internal port, internal client, enabled status, description, and lease duration. +* +* @param[in,out] event - Pointer to action_event structure containing UPnP action request. +* \n Input: NewRemoteHost (string), NewExternalPort (UINT16), NewProtocol (string). +* \n Output: Internal port, internal client, enabled, description, lease duration. +* +* @return The status of the operation. +* @retval PAL_UPNP_E_SUCCESS if successful. +* @retval IGD_GENERAL_ERROR if input parameter is NULL. +* @retval PAL_UPNP_SOAP_E_ACTION_FAILED if service private data is NULL. +* @retval PAL_UPNP_SOAP_E_INVALID_ARGS if XML parsing fails or remote host format is invalid (must be x.x.x.x). +* +*/ INT32 IGD_get_SpecificPortMapping_entry(INOUT struct action_event *event); - /************************************************************ - * Function: IGD_add_PortMapping - * - * Parameters: - * event: INOUT. action request from upnp template - * - * Description: - * This function process the action "IGD_add_PortMapping". - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ +/** +* @brief Add a port mapping entry. +* +* Creates a new port mapping entry with specified parameters. +* \n Validates remote host and internal client IP address formats (x.x.x.x). +* \n Verifies internal client matches control point address and is within valid subnet. +* \n Checks for conflicts with SpeedBoost port ranges if SPEED_BOOST_SUPPORTED is enabled. +* \n Sets lease time to 86400 seconds (24 hours) for the port mapping rule. +* +* @param[in,out] event - Pointer to action_event structure containing UPnP action request. +* \n Input: All port mapping fields for the new entry. +* \n Output: Empty response on success, error code on failure. +* +* @return The status of the operation. +* @retval PAL_UPNP_E_SUCCESS if successful. +* @retval IGD_GENERAL_ERROR if input parameter is NULL. +* @retval PAL_UPNP_SOAP_E_ACTION_FAILED if service private data is NULL. +* @retval PAL_UPNP_SOAP_E_INVALID_ARGS if XML parsing fails, IP format invalid, or client validation fails. +* @retval Conflict_In_MappingEntry if port conflicts with SpeedBoost port ranges. +* +*/ INT32 IGD_add_PortMapping(INOUT struct action_event *event); - /************************************************************ - * Function: IGD_delete_PortMapping - * - * Parameters: - * event: INOUT. action request from upnp template - * - * Description: - * This function process the action "IGD_delete_PortMapping". - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ +/** +* @brief Delete a port mapping entry. +* +* Removes an existing port mapping entry identified by remote host, external port, and protocol. +* \n Validates remote host IP address format if provided (must be x.x.x.x). +* +* @param[in,out] event - Pointer to action_event structure containing UPnP action request. +* \n Input: NewRemoteHost (string), NewExternalPort (UINT16), NewProtocol (string). +* \n Output: Empty response on success, error code on failure. +* +* @return The status of the operation. +* @retval PAL_UPNP_E_SUCCESS if successful. +* @retval IGD_GENERAL_ERROR if input parameter is NULL. +* @retval PAL_UPNP_SOAP_E_ACTION_FAILED if service private data is NULL. +* @retval PAL_UPNP_SOAP_E_INVALID_ARGS if XML parsing fails or remote host format is invalid. +* +*/ INT32 IGD_delete_PortMapping(INOUT struct action_event *event); #if defined (SPEED_BOOST_SUPPORTED) - /************************************************************************************* - * Function : IGD_checkport_SpeedboostPort - * - * Parameters : - * fp : External and internal port for UPnP mapping - * - * Description: - * check if Extenal or Internal port overlaps with Speedboot Range port - * - * Return : - * TRUE : Ext/Int upnp port range is overlapping with xm speedboost port ranges - * FALSE : Ext/Int upnp port range is NOT overlapping with xm speedboost port ranges - ************************************************************/ + +/** +* @brief Check if port overlaps with SpeedBoost port ranges. +* +* Validates that external and internal UPnP port mapping ports do not overlap +* \n with reserved SpeedBoost port ranges (IPv4 and IPv6). +* +* @param[in] ExternalPort - External port number for UPnP port mapping. +* @param[in] InternalPort - Internal port number for UPnP port mapping. +* +* @return The status of port overlap check. +* @retval TRUE if external or internal port overlaps with SpeedBoost port ranges. +* @retval FALSE if no overlap detected or SpeedBoost is disabled. +* +*/ INT32 IGD_checkport_SpeedboostPort(UINT16 ExternalPort, UINT16 InternalPort); #endif - + /***************************interface function end***********************/ #endif //_IGD_ACTION_PORT_MAPPING_ diff --git a/source/igd/src/inc/igd_platform_independent_inf.h b/source/igd/src/inc/igd_platform_independent_inf.h index 8cf18be9..e76bc2d5 100644 --- a/source/igd/src/inc/igd_platform_independent_inf.h +++ b/source/igd/src/inc/igd_platform_independent_inf.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -36,7 +36,7 @@ /* * FileName: igd_platform_independent_inf.h * Author: Andy Liu(zhihliu@cisco.com) Tao Hong(tahong@cisco.com) - * Jianrong(jianxiao@cisco.com)Lipin Zhou(zlipin@cisco.com) + * Jianrong(jianxiao@cisco.com)Lipin Zhou(zlipin@cisco.com) * Date: 2009-05-03 * Description: Header file including all Product-related macro and functions *****************************************************************************/ @@ -90,11 +90,11 @@ /*********************************************************************** * (1) Product-related macro -* Notes: All the below macro should be modified based on your needs +* Notes: All the below macro should be modified based on your needs * when you port IGD to your products ************************************************************************/ -// The name of the lan interface that the IGD will be run on +// The name of the lan interface that the IGD will be run on //#define IGD_UPNP_INTERFACE "lan0" //Now pulled from syscfg @@ -117,132 +117,111 @@ #endif /*********************************************************************** * (2) Product-related functions -* Notes: All the below functions should be implemented based on your +* Notes: All the below functions should be implemented based on your * products when you port IGD to them ************************************************************************/ -/************************************************************ - * Function: IGD_pii_get_serial_number - * - * Parameters: - * NONE - * - * Description: - * Get the serial number of the your product. - * It will be used in the description file of the IGD device - * - * Return Values: CHAR* - * The serial number of the IGD. NULL if failure. - ************************************************************/ +/** +* @brief Get the serial number of the product. +* +* Retrieves the serial number from the product database. +* \n The serial number is used in the UPnP IGD device description file. +* +* @return Pointer to static buffer containing serial number string. +* @retval CHAR* pointer to serial number of IGD if successful. +* @retval NULL if failure or serial number not available. +* +*/ extern CHAR* IGD_pii_get_serial_number(VOID); -/************************************************************ - * Function: IGD_pii_get_uuid - * - * Parameters: - * uuid: OUT. The UUID of one new device. - * - * Description: - * Get the UUID for one new device. - * - * According to the UNnP spec, the different device MUST have the different - * UUID. Our IGD stack will call this function to get one new UUID when - * create one new device. That means, this function MUST return the different - * UUID when it is called every time. And one method to create UUID is provided - * in the "igd_platform_independent_inf.c". - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ -#define UPNP_UUID_LEN_BY_VENDER 42 +#define UPNP_UUID_LEN_BY_VENDER 42 + +/** +* @brief Get UUID for a new UPnP device. +* +* Generates a unique UUID for each UPnP device instance. +* \n According to UPnP specification, each device MUST have a different UUID. +* \n Our IGD stack will call this function to get one new UUID when +* \n create one new device. That means, this function MUST return the different +* \n UUID when it is called every time. And one method to create UUID is provided +* \n in the "igd_platform_independent_inf.c". +* +* @param[out] uuid - Buffer to store the generated UUID string. +* \n Must be allocated with minimum size of UPNP_UUID_LEN_BY_VENDER (42 bytes). +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval -1 if uuid parameter is NULL or MAC address retrieval fails. +* +*/ extern INT32 IGD_pii_get_uuid(OUT CHAR *uuid); -/************************************************************ - * Function: IGD_pii_get_wan_device_number - * - * Parameters: - * NONE - * - * Description: - * Get the instance number of the WANDevice in IGD device - * - * Return Values: INT32 - * The instance number of the WAN device. -1 if failure. - ************************************************************/ +/** +* @brief Get the instance number of WANDevice in IGD device. +* +* Returns the number of WANDevice instances supported by the IGD device. +* +* @return The instance number of WAN devices. +* @retval Instance number of the WAN device on success +* @retval -1 if failure. +* +*/ extern INT32 IGD_pii_get_wan_device_number(VOID); -/************************************************************ - * Function: IGD_pii_get_wan_connection_device_number - * - * Parameters: - * WanDeviceIndex: IN. Index of WANDevice, range:1-Number of WANDevice - * - * Description: - * Get the instance number of the WANConnectionDevice - * in one WANDevice specified by the input device index. - * - * Return Values: INT32 - * The instance number of the WANConnectionDevice. -1 if failure. - ************************************************************/ +/** +* @brief Get the instance number of WANConnectionDevice. +* +* Returns the number of WANConnectionDevice instances in in one WANDevice specified by the input device index. +* +* @param[in] wan_device_index - Index of WANDevice, range: 1 to Number of WANDevices. +* +* @return The instance number of WANConnectionDevice. +* @retval Instance number of the WAN connection device on success. +* @retval -1 if failure. +* +*/ extern INT32 IGD_pii_get_wan_connection_device_number(IN INT32 wan_device_index); -/************************************************************ - * Function: IGD_pii_get_wan_ppp_service_number - * - * Parameters: - * WanDeviceIndex: IN. Index of WANDevice, range:1-Number of WANDevice - * WanConnectionDeviceIndex: IN. Index of WANConnectionDevice, range:1-Number of WANConnectionDevice - * - * Description: - * Get the instance number of the WANPPPConnectionService - * in one WANConnectionDevice specified by the input device index - * - * Return Values: INT32 - * The instance number of WANPPPConnectionService, -1 if failure. - ************************************************************/ +/** +* @brief Get the instance number of WANPPPConnectionService. +* +* Returns the number of WANPPPConnectionService instances in one WANConnectionDevice +* specified by the input device index. +* +* @param[in] WanDeviceIndex - Index of WANDevice, range: 1 to Number of WANDevices. +* @param[in] WanConnectionDeviceIndex - Index of WANConnectionDevice, range: 1 to Number of WANConnectionDevices. +* +* @return The instance number of WANPPPConnectionService. +* @retval Instance number of the WAN PPP connection service on success. +* @retval 0 No PPP connection service (not supported) +* @retval -1 if failure. +* +*/ extern INT32 IGD_pii_get_wan_ppp_service_number(IN INT32 WanDeviceIndex, IN INT32 WanConnectionDeviceIndex); -/************************************************************ - * Function: IGD_pii_get_wan_ip_service_number - * - * Parameters: - * WanDeviceIndex: IN. Index of WANDevice, range:1-Number of WANDevice - * WanConnectionDeviceIndex: IN. Index of WANConnectionDevice, range:1-Number of WANConnectionDevice - * - * Description: - * Get the instance number of the WANIPConnectionService - * in one WANConnectionDevice specified by the input device index - * - * Return Values: INT32 - * The instance number of WANIPConnectionService, -1 if failure. - ************************************************************/ +/** +* @brief Get the instance number of WANIPConnectionService. +* +* Returns the number of WANIPConnectionService instances in one WANConnectionDevice +* specified by the input device index. +* \n Related UPnP Device/Service: WANIPConnectionService. +* +* @param[in] WanDeviceIndex - Index of WANDevice, range: 1 to Number of WANDevices. +* @param[in] WanConnectionDeviceIndex - Index of WANConnectionDevice, range: 1 to Number of WANConnectionDevices. +* +* @return The instance number of WANIPConnectionService. +* @retval Instance number of WANIPConnectionService on success +* @retval -1 if failure. +* +*/ extern INT32 IGD_pii_get_wan_ip_service_number(IN INT32 WanDeviceIndex, IN INT32 WanConnectionDeviceIndex); -/************************************************************ - * Function: IGD_pii_get_possible_connection_types - * - * Parameters: - * WanDeviceIndex: IN. Index of WANDevice, range:1-Number of WANDevice. - * WanConnectionDeviceIndex: IN. Index of WANConnectionDevice, range:1-Number of WANConnectionDevice. - * WanConnectionServiceIndex: IN. Index of WAN(IP/PPP)ConnectionService,range:1-Number of WAN(IP/PPP)ConnectionService minimum value is 1. - * ServiceType: IN. Type of WANXXXXConnection. - * ConnectionTypesList: OUT. List of possible connection types, a comma-separated - * string.One example for WANIPConnection is "Unconfigured,IP_Routed,IP_Bridged". - * - * Description: - * Get the list of possbile connection types of one WAN(IP/PPP)ConnectionService - * specified by the input device index and service type - * Related UPnP Device/Service: WAN(IP/PPP)ConnectionService - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ -// The valid value of the input parameter,"ServiceType" +// The valid value of the input parameter,"ServiceType" #define SERVICETYPE_IP (1) #define SERVICETYPE_PPP (2) -// The valid value of the output parameter,"ConnectionTypesList" +// The valid value of the output parameter,"ConnectionTypesList" // possible IP connection types #define IPCONNTYPE_UNCONFIGURED "Unconfigured" #define IPCONNTYPE_IP_ROUTED "IP_Routed" @@ -254,211 +233,256 @@ extern INT32 IGD_pii_get_wan_ip_service_number(IN INT32 WanDeviceIndex, #define PPPCONNTYPE_PPPOE_BRIDGED "PPPoE_Bridged" #define PPPCONNTYPE_PPTP_RELAY "PPTP_Relay" #define PPPCONNTYPE_L2TP_RELAY "L2TP_Relay" -#define PPPCONNTYPE_PPPOE_RELAY "PPPoE_Relay" - +#define PPPCONNTYPE_PPPOE_RELAY "PPPoE_Relay" + +/** +* @brief Get list of possible connection types. +* +* Retrieves the list of possible connection types for the specified WAN connection service +* specified by the input device index and service type. +* \n Returns a comma-separated string of connection types. +* \n For IP connections: "Unconfigured,IP_Routed,IP_Bridged". +* \n For PPP connections: "Unconfigured,IP_Routed,DHCP_Spoofed,PPPoE_Bridged,PPTP_Relay,L2TP_Relay,PPPoE_Relay". +* \n Related UPnP Device/Service: WAN(IP/PPP)ConnectionService. +* +* @param[in] WanDeviceIndex - Index of WANDevice, range: 1 to Number of WANDevices. +* @param[in] WanConnectionDeviceIndex - Index of WANConnectionDevice, range: 1 to Number of WANConnectionDevices. +* @param[in] WanConnectionServiceIndex - Index of WAN(IP/PPP)ConnectionService, range: 1 to Number of services. +* @param[in] ServiceType - Type of WAN connection service. +* \n Valid values: SERVICETYPE_IP (1) or SERVICETYPE_PPP (2). +* @param[out] ConnectionTypesList - Buffer to store comma-separated list of possible connection types. +* \n Buffer should be allocated with sufficient size (recommend UPNP_LINE_SIZE). +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval Non-zero error code if failure. +* +*/ extern INT32 IGD_pii_get_possible_connection_types(IN INT32 WanDeviceIndex, IN INT32 WanConnectionDeviceIndex, IN INT32 WanConnectionServiceIndex, IN INT32 ServiceType, OUT CHAR *ConnectionTypesList); -/************************************************************ - * Function: IGD_pii_get_connection_status - * - * Parameters: - * WanDeviceIndex: IN. Index of WANDevice, range:1-Number of WANDevice. - * WanConnectionDeviceIndex: IN. Index of WANConnectionDevice, range:1-Number of WANConnectionDevice.. - * WanConnectionServiceIndex: IN. Index of WAN(IP/PPP)ConnectionService,range:1-Number of WAN(IP/PPP)ConnectionService - * ServiceType: IN. Type of WAN connection service. - * ConnectionType: OUT. Current connection status. - * - * Description: - * Get the current connection status of one WAN(IP/PPP)ConnectionService - * specified by the input device index and service type - * Related UPnP Device/Service: WAN(IP/PPP)ConnectionService - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ - -// The valid value of the output parameter,"ConnectionStatus" + +// The valid value of the output parameter,"ConnectionStatus" // possible connection status, for both IP and PPP #define CONNSTATUS_UNCONFIGURED "Unconfigured" #define CONNSTATUS_CONNECTED "Connected" -#define CONNSTATUS_DISCONNECTED "Disconnected" - +#define CONNSTATUS_DISCONNECTED "Disconnected" + +/** +* @brief Get current connection status. +* +* Retrieves the current connection status of the specified WAN connection service +* specified by the input device index and service type. +* \n Reads WAN connection status from Utopia context. +* \n Possible values: "Connected", "Connecting", "Disconnecting", "Disconnected", "Unconfigured". +* \n Related UPnP Device/Service: WAN(IP/PPP)ConnectionService. +* +* @param[in] WanDeviceIndex - Index of WANDevice, range: 1 to Number of WANDevices. +* @param[in] WanConnectionDeviceIndex - Index of WANConnectionDevice, range: 1 to Number of WANConnectionDevices. +* @param[in] WanConnectionServiceIndex - Index of WAN(IP/PPP)ConnectionService, range: 1 to Number of services. +* @param[in] ServiceType - Type of WAN connection service. +* \n Valid values: SERVICETYPE_IP (1) or SERVICETYPE_PPP (2). +* @param[out] ConnectionStatus - Buffer to store current connection status string. +* \n Buffer should be allocated with sufficient size (recommend UPNP_LINE_SIZE). +* \n Values: CONNSTATUS_UNCONFIGURED, CONNSTATUS_CONNECTED, CONNSTATUS_DISCONNECTED. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval 1 if error retrieving WAN connection status from Utopia. +* +*/ extern INT32 IGD_pii_get_connection_status(IN INT32 WanDeviceIndex, IN INT32 WanConnectionDeviceIndex, IN INT32 WanConnectionServiceIndex, IN INT32 ServiceType, OUT CHAR *ConnectionStatus); -/************************************************************ - * Function: IGD_pii_get_connection_type - * - * Parameters: - * WanDeviceIndex: IN. Index of WANDevice, range:1-Number of WANDevice. - * WanConnectionDeviceIndex: IN. Index of WANConnectionDevice, range:1-Number of WANConnectionDevice.. - * WanWAN(IP/PPP)ConnectionServiceIndex: IN. Index of WAN(IP/PPP)ConnectionService,range:1-Number of WAN(IP/PPP)ConnectionService - * ServiceType: IN. Type of WAN connection service. - * ConnectionType: OUT. Current connection type. - * - * Description: - * Get the current connection type of one WAN(IP/PPP)ConnectionService - * specified by the input device index and service type - * Related UPnP Device/Service: WAN(IP/PPP)ConnectionService - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ - -// The valid value of the output parameter,"ConnectionType" -// Same as the output parameter,"ConnectionTypesList", of IGD_pii_get_possible_connection_types() + + +/** +* @brief Get current connection type. +* +* Retrieves the current connection type of the specified WAN connection service +* specified by the input device index and service type. +* \n Related UPnP Device/Service: WAN(IP/PPP)ConnectionService. +* +* @param[in] WanDeviceIndex - Index of WANDevice, range: 1 to Number of WANDevices. +* @param[in] WanConnectionDeviceIndex - Index of WANConnectionDevice, range: 1 to Number of WANConnectionDevices. +* @param[in] WanConnectionServiceIndex - Index of WAN(IP/PPP)ConnectionService, range: 1 to Number of services. +* @param[in] ServiceType - Type of WAN connection service. +* \n Valid values: SERVICETYPE_IP (1) or SERVICETYPE_PPP (2). +* @param[out] ConnectionType - Buffer to store current connection type string. +* \n Buffer should be allocated with sufficient size (recommend UPNP_LINE_SIZE). +* \n Valid values same as ConnectionTypesList from IGD_pii_get_possible_connection_types(). +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval Non-zero error code if failure. +* +*/ extern INT32 IGD_pii_get_connection_type(IN INT32 WanDeviceIndex, IN INT32 WanConnectionDeviceIndex, IN INT32 WanConnectionServiceIndex, IN INT32 ServiceType, OUT CHAR *ConnectionType); - -/************************************************************ - * Function: IGD_pii_set_connection_type - * - * Parameters: - * WanDeviceIndex: IN. Index of WANDevice, range:1-Number of WANDevice. - * WanConnectionDeviceIndex: IN. Index of WANConnectionDevice, range:1-Number of WANConnectionDevice.. - * WanConnectionServiceIndex: IN. Index of WAN(IP/PPP)ConnectionService,range:1-Number of WAN(IP/PPP)ConnectionService - * ServiceType: IN. Type of WAN(IP/PPP)connectionService. - * ConnectionType: IN. The connection type that will be set. - * - * Description: - * Set the current connection type of one WAN(IP/PPP)connectionService - * specified by the input device index and service type - * Related UPnP Device/Service: WAN(IP/PPP)ConnectionService - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ - -// The valid value of the input parameter,"ConnectionType" -// Same as the output parameter,"ConnectionTypesList", of IGD_pii_get_possible_connection_types() +/** +* @brief Set connection type. +* +* Sets the connection type for the specified WAN connection service +* specified by the input device index and service type. +* \n Stores the connection type value in internal static buffer. +* \n Related UPnP Device/Service: WAN(IP/PPP)ConnectionService. +* +* @param[in] WanDeviceIndex - Index of WANDevice, range: 1 to Number of WANDevices. +* @param[in] WanConnectionDeviceIndex - Index of WANConnectionDevice, range: 1 to Number of WANConnectionDevices. +* @param[in] WanConnectionServiceIndex - Index of WAN(IP/PPP)ConnectionService, range: 1 to Number of services. +* @param[in] ServiceType - Type of WAN connection service. +* \n Valid values: SERVICETYPE_IP (1) or SERVICETYPE_PPP (2). +* @param[in] ConnectionType - Connection type string to set. +* \n Valid values same as ConnectionTypesList from IGD_pii_get_possible_connection_types(). +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval Non-zero error code if failure. +* +*/ extern INT32 IGD_pii_set_connection_type(IN INT32 WanDeviceIndex, IN INT32 WanConnectionDeviceIndex, IN INT32 WanConnectionServiceIndex, IN INT32 ServiceType, IN CHAR *ConnectionType); - -/************************************************************ - * Function: IGD_pii_request_connection - * - * Parameters: - * WanDeviceIndex: IN. Index of WANDevice, range:1-Number of WANDevice. - * WanConnectionDeviceIndex: IN. Index of WANConnectionDevice, range:1-Number of WANConnectionDevice.. - * WanConnectionServiceIndex: IN. Index of WAN(IP/PPP)ConnectionService,range:1-Number of WAN(IP/PPP)ConnectionService - * ServiceType: IN. Type of WAN(IP/PPP)connectionService. - * ConnectionType: IN. The connection type that will be set. - * - * Description: - * Request to initiate the connection of WAN(IP/PPP)connectionService - * specified by the input device index and service type - * Related UPnP Device/Service: WAN(IP/PPP)ConnectionService - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ + + +// The valid value of the input parameter,"ConnectionType" +// Same as the output parameter,"ConnectionTypesList", of IGD_pii_get_possible_connection_types() + +/** +* @brief Request to initiate WAN connection. +* +* Initiates the connection for the specified WAN connection service +* specified by the input device index and service type. +* \n Related UPnP Device/Service: WAN(IP/PPP)ConnectionService. +* +* @param[in] WanDeviceIndex - Index of WANDevice, range: 1 to Number of WANDevices. +* @param[in] WanConnectionDeviceIndex - Index of WANConnectionDevice, range: 1 to Number of WANConnectionDevices. +* @param[in] WanConnectionServiceIndex - Index of WAN(IP/PPP)ConnectionService, range: 1 to Number of services. +* @param[in] ServiceType - Type of WAN connection service. +* \n Valid values: SERVICETYPE_IP (1) or SERVICETYPE_PPP (2). +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval Non-zero error code if failure. +* +*/ extern INT32 IGD_pii_request_connection(IN INT32 WanDeviceIndex, IN INT32 WanConnectionDeviceIndex, IN INT32 WanConnectionServiceIndex, IN INT32 ServiceType); - -/************************************************************ - * Function: IGD_pii_force_termination - * - * Parameters: - * WanDeviceIndex: IN. Index of WANDevice, range:1-Number of WANDevice. - * WanConnectionDeviceIndex: IN. Index of WANConnectionDevice, range:1-Number of WANConnectionDevice.. - * WanConnectionServiceIndex: IN. Index of WAN(IP/PPP)ConnectionService,range:1-Number of WAN(IP/PPP)ConnectionService - * ServiceType: IN. Type of WAN(IP/PPP)connectionService. - * ConnectionType: IN. The connection type that will be set. - * - * Description: - * Force to terminate the connection of WAN(IP/PPP)connectionService - * specified by the input device index and service type - * Related UPnP Device/Service: WAN(IP/PPP)ConnectionService - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ + +/** +* @brief Force terminate WAN connection. +* +* Forces termination of the connection for the specified WAN connection service +* specified by the input device index and service type. +* \n Checks if IGD internet disable is allowed. If allowed, terminate the connection. +* \n Related UPnP Device/Service: WAN(IP/PPP)ConnectionService. +* +* @param[in] WanDeviceIndex - Index of WANDevice, range: 1 to Number of WANDevices. +* @param[in] WanConnectionDeviceIndex - Index of WANConnectionDevice, range: 1 to Number of WANConnectionDevices. +* @param[in] WanConnectionServiceIndex - Index of WAN(IP/PPP)ConnectionService, range: 1 to Number of services. +* @param[in] ServiceType - Type of WAN connection service. +* \n Valid values: SERVICETYPE_IP (1) or SERVICETYPE_PPP (2). +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval 1 if termination not allowed or WAN connection termination fails. +* +*/ extern INT32 IGD_pii_force_termination(IN INT32 WanDeviceIndex, IN INT32 WanConnectionDeviceIndex, IN INT32 WanConnectionServiceIndex, IN INT32 ServiceType); - -/************************************************************ - * Function: IGD_pii_get_external_ip - * - * Parameters: - * WanDeviceIndex: IN. Index of WANDevice, range:1-Number of WANDevice. - * WanConnectionDeviceIndex: IN. Index of WANConnectionDevice, range:1-Number of WANConnectionDevice.. - * WanConnectionServiceIndex: IN. Index of WAN(IP/PPP)ConnectionService,range:1-Number of WAN(IP/PPP)ConnectionService - * ServiceType: IN. Type of WAN(IP/PPP)connectionService. - * ExternalIp: OUT. External IP address in string format. - * - * Description: - * Get current external IP address used by NAT for the connection of WAN(IP/PPP)connectionService - * specified by the input device index and service type - * Related UPnP Device/Service: WAN(IP/PPP)ConnectionService - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ + +/** +* @brief Get external IP address. +* +* Retrieves the current external IP address used by NAT for the WAN connection +* specified by the input device index and service type. +* \n Reads WAN connection status from Utopia context and returns the IP address. +* \n Related UPnP Device/Service: WAN(IP/PPP)ConnectionService. +* +* @param[in] WanDeviceIndex - Index of WANDevice, range: 1 to Number of WANDevices. +* @param[in] WanConnectionDeviceIndex - Index of WANConnectionDevice, range: 1 to Number of WANConnectionDevices. +* @param[in] WanConnectionServiceIndex - Index of WAN(IP/PPP)ConnectionService, range: 1 to Number of services. +* @param[in] ServiceType - Type of WAN connection service. +* \n Valid values: SERVICETYPE_IP (1) or SERVICETYPE_PPP (2). +* @param[out] ExternalIp - Buffer to store external IP address in string format (x.x.x.x). +* \n Buffer should be allocated with at least IPV4_ADDR_LEN bytes. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval 1 if error retrieving WAN connection status from Utopia. +* +*/ extern INT32 IGD_pii_get_external_ip(IN INT32 WanDeviceIndex, IN INT32 WanConnectionDeviceIndex, IN INT32 WanConnectionServiceIndex, IN INT32 ServiceType, OUT CHAR *ExternalIp); - -/************************************************************ - * Function: IGD_pii_get_link_layer_max_bitrate - * - * Parameters: - * WanDeviceIndex: IN. Index of WANDevice, range:1-Number of WANDevice. - * WanConnectionDeviceIndex: IN. Index of WANConnectionDevice, range:1-Number of WANConnectionDevice.. - * WanConnectionServiceIndex: IN. Index of WAN(IP/PPP)ConnectionService,range:1-Number of WAN(IP/PPP)ConnectionService - * ServiceType: IN. Type of WAN(IP/PPP)connectionService. - * UpRate: OUT. Maximum upstream bitrate, it has a static value once a connection is setup. - * DownRate: OUT. Maximum downstream bitrate, it has a static value once a connection is setup. - * - * Description: - * Get the link layer maximum bitrates(upstream and downstream) for the connection of WAN(IP/PPP)connectionService - * specified by the input device index and service type - * Related UPnP Device/Service: WAN(IP/PPP)ConnectionService - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ + +/** +* @brief Get link layer maximum bitrates. +* +* Retrieves the maximum upstream and downstream bitrates for the WAN connection +* specified by the input device index and service type. +* \n These values are static once a connection is established. +* \n Related UPnP Device/Service: WAN(IP/PPP)ConnectionService. +* +* @param[in] WanDeviceIndex - Index of WANDevice, range: 1 to Number of WANDevices. +* @param[in] WanConnectionDeviceIndex - Index of WANConnectionDevice, range: 1 to Number of WANConnectionDevices. +* @param[in] WanConnectionServiceIndex - Index of WAN(IP/PPP)ConnectionService, range: 1 to Number of services. +* @param[in] ServiceType - Type of WAN connection service. +* \n Valid values: SERVICETYPE_IP (1) or SERVICETYPE_PPP (2). +* @param[out] UpRate - Buffer to store maximum upstream bitrate in bits per second. +* \n Buffer should be allocated with sufficient size (recommend UPNP_LINE_SIZE). +* @param[out] DownRate - Buffer to store maximum downstream bitrate in bits per second. +* \n Buffer should be allocated with sufficient size (recommend UPNP_LINE_SIZE). +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval Non-zero error code if failure. +* +*/ extern INT32 IGD_pii_get_link_layer_max_bitrate(IN INT32 WanDeviceIndex, IN INT32 WanConnectionDeviceIndex, IN INT32 WanConnectionServiceIndex, IN INT32 ServiceType, OUT CHAR *UpRate, OUT CHAR *DownRate); - -/************************************************************ - * Function: IGD_pii_get_up_time - * - * Parameters: - * WanDeviceIndex: IN. Index of WANDevice, range:1-Number of WANDevice. - * WanConnectionDeviceIndex: IN. Index of WANConnectionDevice, range:1-Number of WANConnectionDevice.. - * WanConnectionServiceIndex: IN. Index of WAN(IP/PPP)ConnectionService,range:1-Number of WAN(IP/PPP)ConnectionService - * ServiceType: IN. Type of WAN(IP/PPP)connectionService. - * UpTime: OUT. The time in seconds that this connection has stayed up. - * - * Description: - * Get the time in seconds that the connection has stayed up. - * Related UPnP Device/Service: WAN(IP/PPP)ConnectionService - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ + +/** +* @brief Get WAN connection uptime. +* +* Retrieves the time in seconds that the WAN connection has stayed up. +* \n Reads WAN connection status from Utopia context and returns the uptime value. +* \n Related UPnP Device/Service: WAN(IP/PPP)ConnectionService. +* +* @param[in] WanDeviceIndex - Index of WANDevice, range: 1 to Number of WANDevices. +* @param[in] WanConnectionDeviceIndex - Index of WANConnectionDevice, range: 1 to Number of WANConnectionDevices. +* @param[in] WanConnectionServiceIndex - Index of WAN(IP/PPP)ConnectionService, range: 1 to Number of services. +* @param[in] ServiceType - Type of WAN connection service. +* \n Valid values: SERVICETYPE_IP (1) or SERVICETYPE_PPP (2). +* @param[out] UpTime - Buffer to store connection uptime in seconds. +* \n Buffer should be allocated with sufficient size (recommend UPNP_LINE_SIZE). +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval 1 if error retrieving WAN connection status from Utopia. +* +*/ extern INT32 IGD_pii_get_up_time(IN INT32 WanDeviceIndex, IN INT32 WanConnectionDeviceIndex, IN INT32 WanConnectionServiceIndex, @@ -466,51 +490,38 @@ extern INT32 IGD_pii_get_up_time(IN INT32 WanDeviceIndex, OUT CHAR *UpTime); -/************************************************************ - * Function: IGD_pii_get_NAT_RSIP_status - * - * Parameters: - * WanDeviceIndex: IN. Index of WANDevice, range:1-Number of WANDevice. - * WanConnectionDeviceIndex: IN. Index of WANConnectionDevice, range:1-Number of WANConnectionDevice.. - * WanConnectionServiceIndex: IN. Index of WAN(IP/PPP)ConnectionService,range:1-Number of WAN(IP/PPP)ConnectionService - * ServiceType: IN. Type of WAN(IP/PPP)connectionService. - * NATEnable: OUT. Value=1(NAT is enabled) or 0(NAT is disabled) - * RSIPAvailable: OUT. Value=1(RSIP is supported) or 0(RSIP isn't supported) - * - * Description: - * Get the current state of NAT and RSIP for the connection of WAN(IP/PPP)connectionService - * specified by the input device index and service type - * Related UPnP Device/Service: WAN(IP/PPP)ConnectionService - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ +/** +* @brief Get NAT and RSIP status. +* +* Retrieves the current state of NAT (Network Address Translation) and RSIP (Realm Specific IP) +* specified by the input device index and service type. +* \n Reads NAT enable status and RSIP status from Utopia context. +* \n Related UPnP Device/Service: WAN(IP/PPP)ConnectionService. +* +* @param[in] WanDeviceIndex - Index of WANDevice, range: 1 to Number of WANDevices. +* @param[in] WanConnectionDeviceIndex - Index of WANConnectionDevice, range: 1 to Number of WANConnectionDevices. +* @param[in] WanConnectionServiceIndex - Index of WAN(IP/PPP)ConnectionService, range: 1 to Number of services. +* @param[in] ServiceType - Type of WAN connection service. +* \n Valid values: SERVICETYPE_IP (1) or SERVICETYPE_PPP (2). +* @param[out] NATEnable - Pointer to BOOL variable to store NAT enable status. +* \n Value: BOOL_TRUE (1) if NAT is enabled, BOOL_FALSE (0) if disabled. +* @param[out] RSIPAvailable - Pointer to BOOL variable to store RSIP availability. +* \n Value: BOOL_TRUE (1) if RSIP supported, BOOL_FALSE (0) if not supported. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval Non-zero error code if failure. +* +*/ extern INT32 IGD_pii_get_NAT_RSIP_status( IN INT32 WanDeviceIndex, IN INT32 WanConnectionDeviceIndex, - IN INT32 WanConnectionServiceIndex, + IN INT32 WanConnectionServiceIndex, IN INT32 ServiceType, - OUT BOOL *NATEnable, - OUT BOOL *RSIPAvailable ); - + OUT BOOL *NATEnable, + OUT BOOL *RSIPAvailable ); + + -/************************************************************ - * Function: IGD_pii_add_portmapping_entry - * - * Parameters: - * WanDeviceIndex: IN. Index of WANDevice, range:1-Number of WANDevice. - * WanConnectionDeviceIndex: IN. Index of WANConnectionDevice, range:1-Number of WANConnectionDevice.. - * WanConnectionServiceIndex: IN. Index of WAN(IP/PPP)ConnectionService,range:1-Number of WAN(IP/PPP)ConnectionService - * ServiceType: IN. Type of WAN(IP/PPP)connectionService. - * PortmappingEntry: IN. The portmapping entry to be added. - * - * Description: - * Add a new port mapping or overwrites an existing mapping with the same internal client. - * Related UPnP Device/Service: WAN(IP/PPP)ConnectionService - * - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ //Structure definition for the output parameter,"PortmappingEntry" #define PORT_MAP_PROTOCOL_LEN 4 @@ -527,7 +538,7 @@ typedef struct IGD_PortMapping_Entry{ BOOL enabled; //"PortMappingEnabled" CHAR description[NAME_SZ]; //"PortMappingDescription" UINT32 leaseTime; //"PortMappingLeaseDuration" -}IGD_PortMapping_Entry, *PIGD_PortMapping_Entry; +}IGD_PortMapping_Entry, *PIGD_PortMapping_Entry; //Error code #define ERROR_PORTMAPPING_ADD_FAILED -501 @@ -539,209 +550,259 @@ typedef struct IGD_PortMapping_Entry{ #define ERROR_REMOST_HOST_ONLY_SUPPORT_WILDCARD -726 //RemoteHost must be a wildcard and cannot be a specific IP address or DNS name #define ERROR_EXTERNAL_PORT_ONLY_SUPPORT_WILDCARD -727 //ExternalPort must be a wildcard and cannot be a specific port value +/** +* @brief Add a new port mapping entry. +* +* Creates a new port mapping entry or updates an existing mapping with the same internal client. +* \n Check if entry exists and If entry exists for same internal client, updates lease time and description. +* \n If entry exists for different internal client, returns ERROR_CONFLICT_FOR_MAPPING_ENTRY. +* \n For new entries, add to configuration. +* \n Related UPnP Device/Service: WAN(IP/PPP)ConnectionService. +* +* @param[in] WanDeviceIndex - Index of WANDevice, range: 1 to Number of WANDevices. +* @param[in] WanConnectionDeviceIndex - Index of WANConnectionDevice, range: 1 to Number of WANConnectionDevices. +* @param[in] WanConnectionServiceIndex - Index of WAN(IP/PPP)ConnectionService, range: 1 to Number of services. +* @param[in] ServiceType - Type of WAN connection service. +* \n Valid values: SERVICETYPE_IP (1) or SERVICETYPE_PPP (2). +* @param[in] PortmappingEntry - Pointer to IGD_PortMapping_Entry structure containing port mapping details. +* \n Required fields: remoteHost, externalPort, protocol, internalPort, +* \n internalClient, enabled, description, leaseTime. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval 1 if IGD configuration disabled or addition fails. +* @retval ERROR_CONFLICT_FOR_MAPPING_ENTRY if entry conflicts with existing mapping for different client. +* +*/ extern INT32 IGD_pii_add_portmapping_entry( IN INT32 WanDeviceIndex, IN INT32 WanConnectionDeviceIndex, - IN INT32 WanConnectionServiceIndex, + IN INT32 WanConnectionServiceIndex, IN INT32 ServiceType, IN PIGD_PortMapping_Entry PortmappingEntry); - -/************************************************************ - * Function: IGD_pii_del_portmapping_entry - * - * Parameters: - * WanDeviceIndex: IN. Index of WANDevice, range:1-Number of WANDevice. - * WanConnectionDeviceIndex: IN. Index of WANConnectionDevice, range:1-Number of WANConnectionDevice.. - * WanConnectionServiceIndex: IN. Index of WAN(IP/PPP)ConnectionService,range:1-Number of WAN(IP/PPP)ConnectionService - * ServiceType: IN. Type of WAN(IP/PPP)connectionService. - * RemoteHost: IN. Remote host. - * ExternalPort: IN. External port. - * Protocol: IN. PortMapping protocol. - * - * Description: - * Delete a previously instantiated port mapping. - * Related UPnP Device/Service: WAN(IP/PPP)ConnectionService - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ + +/** +* @brief Delete a port mapping entry. +* +* Removes a previously instantiated port mapping identified by RemoteHost, ExternalPort, and Protocol from configuration. +* \n Related UPnP Device/Service: WAN(IP/PPP)ConnectionService. +* +* @param[in] WanDeviceIndex - Index of WANDevice, range: 1 to Number of WANDevices. +* @param[in] WanConnectionDeviceIndex - Index of WANConnectionDevice, range: 1 to Number of WANConnectionDevices. +* @param[in] WanConnectionServiceIndex - Index of WAN(IP/PPP)ConnectionService, range: 1 to Number of services. +* @param[in] ServiceType - Type of WAN connection service. +* \n Valid values: SERVICETYPE_IP (1) or SERVICETYPE_PPP (2). +* @param[in] RemoteHost - Remote host IP address string. +* @param[in] ExternalPort - External port number. +* @param[in] Protocol - Protocol string ("TCP" or "UDP"). +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval 1 if deletion fails or entry not found. +* +*/ extern INT32 IGD_pii_del_portmapping_entry( IN INT32 WanDeviceIndex, IN INT32 WanConnectionDeviceIndex, - IN INT32 WanConnectionServiceIndex, + IN INT32 WanConnectionServiceIndex, IN INT32 ServiceType, IN CHAR *RemoteHost, IN UINT16 ExternalPort, IN CHAR *Protocol); - - /************************************************************ - * Function: IGD_pii_get_portmapping_entry_num - * - * Parameters: - * WanDeviceIndex: IN. Index of WANDevice, range:1-Number of WANDevice. - * WanConnectionDeviceIndex: IN. Index of WANConnectionDevice, range:1-Number of WANConnectionDevice.. - * WanConnectionServiceIndex: IN. Index of WAN(IP/PPP)ConnectionService,range:1-Number of WAN(IP/PPP)ConnectionService - * ServiceType: IN. Type of WAN(IP/PPP)connectionService. - * PortmappingEntryNum: OUT. The total number of the PortMapping entry . - * - * Description: - * Get the total number of the PortMapping entry. - * Related UPnP Device/Service: WAN(IP/PPP)ConnectionService - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ + +/** +* @brief Get total number of port mapping entries. +* +* Retrieves the total count of configured port mapping entries. +* \n Related UPnP Device/Service: WAN(IP/PPP)ConnectionService. +* +* @param[in] WanDeviceIndex - Index of WANDevice, range: 1 to Number of WANDevices. +* @param[in] WanConnectionDeviceIndex - Index of WANConnectionDevice, range: 1 to Number of WANConnectionDevices. +* @param[in] WanConnectionServiceIndex - Index of WAN(IP/PPP)ConnectionService, range: 1 to Number of services. +* @param[in] ServiceType - Type of WAN connection service. +* \n Valid values: SERVICETYPE_IP (1) or SERVICETYPE_PPP (2). +* @param[out] PortmappingEntryNum - Pointer to INT32 variable to store the total number of port mapping entries. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval Non-zero error code if failure. +* +*/ extern INT32 IGD_pii_get_portmapping_entry_num(IN INT32 WanDeviceIndex, IN INT32 WanConnectionDeviceIndex, - IN INT32 WanConnectionServiceIndex, + IN INT32 WanConnectionServiceIndex, IN INT32 ServiceType, OUT INT32 *PortmappingEntryNum); - -/************************************************************ - * Function: IGD_pii_get_portmapping_entry_generic - * - * Parameters: - * WanDeviceIndex: IN. Index of WANDevice, range:1-Number of WANDevice. - * WanConnectionDeviceIndex: IN. Index of WANConnectionDevice, range:1-Number of WANConnectionDevice.. - * WanConnectionServiceIndex: IN. Index of WAN(IP/PPP)ConnectionService,range:1-Number of WAN(IP/PPP)ConnectionService - * ServiceType: IN. Type of WAN(IP/PPP)connectionService. - * PortmappingIndex: IN. The index of the portmapping entry. Value range: 0-PortmappingEntryNum - * PortmappingEntry: OUT. The portmapping entry. - * - * Description: - * Get one portmapping entry specified by the input index. - * Related UPnP Device/Service: WAN(IP/PPP)ConnectionService - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ -// Error code -#define ERROR_SPECIFIED_INDEX_INVALID -713 //The Specified index is out of bounds - + + +// Error code +#define ERROR_SPECIFIED_INDEX_INVALID -713 //The Specified index is out of bounds + +/** +* @brief Get port mapping entry by index. +* +* Retrieves a specific port mapping entry by its index number. +* \n Index range: 0 to PortmappingEntryNum-1 (IGD uses 0-based indexing). +* \n Populates all fields of the PortmappingEntry structure. +* \n Related UPnP Device/Service: WAN(IP/PPP)ConnectionService. +* +* @param[in] WanDeviceIndex - Index of WANDevice, range: 1 to Number of WANDevices. +* @param[in] WanConnectionDeviceIndex - Index of WANConnectionDevice, range: 1 to Number of WANConnectionDevices. +* @param[in] WanConnectionServiceIndex - Index of WAN(IP/PPP)ConnectionService, range: 1 to Number of services. +* @param[in] ServiceType - Type of WAN connection service. +* \n Valid values: SERVICETYPE_IP (1) or SERVICETYPE_PPP (2). +* @param[in] PortmappingIndex - Index of the port mapping entry to retrieve. +* \n Valid range: 0 to PortmappingEntryNum-1. +* @param[out] PortmappingEntry - Pointer to IGD_PortMapping_Entry structure to store the retrieved entry. +* \n All fields will be populated on success. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval 1 if index out of range or retrieval fails. +* +*/ extern INT32 IGD_pii_get_portmapping_entry_generic( IN INT32 WanDeviceIndex, IN INT32 WanConnectionDeviceIndex, - IN INT32 WanConnectionServiceIndex, + IN INT32 WanConnectionServiceIndex, IN INT32 ServiceType, IN INT32 PortmappingIndex, OUT PIGD_PortMapping_Entry PortmappingEntry); - -/************************************************************ - * Function: IGD_pii_get_portmapping_entry_specific - * - * Parameters: - * WanDeviceIndex: IN. Index of WANDevice, range:1-Number of WANDevice. - * WanConnectionDeviceIndex: IN. Index of WANConnectionDevice, range:1-Number of WANConnectionDevice.. - * WanConnectionServiceIndex: IN. Index of WAN(IP/PPP)ConnectionService,range:1-Number of WAN(IP/PPP)ConnectionService - * ServiceType: IN. Type of WAN(IP/PPP)connectionService. - * PortmappingEntry: INOUT. The portmapping entry. - * - * Description: - * Get one portmapping entry specified by the unique tuple of - * RemoteHost,ExteralPort and Protocol in the input parameter,PortmappingEntry - * - * Related UPnP Device/Service: WAN(IP/PPP)ConnectionService - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ + + /*Special notes for the INOUT parameter,PortmappingEntry typedef struct IGD_PortMapping_Entry{ CHAR remoteHost[IPV4_ADDR_LEN]; //IN UINT16 externalPort; //IN CHAR protocol[PORT_MAP_PROTOCOL_LEN]; //IN - + UINT16 internalPort; //OUT CHAR internalClient[IPV4_ADDR_LEN]; //OUT BOOL enabled; //OUT CHAR description[NAME_SZ]; //OUT UINT32 leaseTime; //OUT }IGD_PortMapping_Entry, *PIGD_PortMapping_Entry; */ - -//Error code + +//Error code #define ERROR_NO_SUCH_ENTRY -714 // The specified value doesn't exist - + +/** +* @brief Get port mapping entry by unique tuple. +* +* Retrieves a specific port mapping entry by its unique tuple of RemoteHost, ExternalPort, and Protocol. +* \n Input: remoteHost, externalPort, protocol fields of PortmappingEntry parameter. +* \n Output: internalPort, internalClient, enabled, description, leaseTime fields. +* \n Related UPnP Device/Service: WAN(IP/PPP)ConnectionService. +* +* @param[in] WanDeviceIndex - Index of WANDevice, range: 1 to Number of WANDevices. +* @param[in] WanConnectionDeviceIndex - Index of WANConnectionDevice, range: 1 to Number of WANConnectionDevices. +* @param[in] WanConnectionServiceIndex - Index of WAN(IP/PPP)ConnectionService, range: 1 to Number of services. +* @param[in] ServiceType - Type of WAN connection service. +* \n Valid values: SERVICETYPE_IP (1) or SERVICETYPE_PPP (2). +* @param[in,out] PortmappingEntry - Pointer to IGD_PortMapping_Entry structure. +* \n INPUT fields: remoteHost, externalPort, protocol. +* \n OUTPUT fields: internalPort, internalClient, enabled, description, leaseTime. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval 1 if entry not found. +* +*/ extern INT32 IGD_pii_get_portmapping_entry_specific( IN INT32 WanDeviceIndex, IN INT32 WanConnectionDeviceIndex, - IN INT32 WanConnectionServiceIndex, + IN INT32 WanConnectionServiceIndex, IN INT32 ServiceType, - INOUT PIGD_PortMapping_Entry PortmappingEntry); + INOUT PIGD_PortMapping_Entry PortmappingEntry); -/************************************************************ - * Function: IGD_pii_get_ethernet_link_status - * - * Parameters: - * WanDeviceIndex: IN. Index of WANDevice, range:1-Number of WANDevice. - * WanConnectionDeviceIndex: IN. Index of WANConnectionDevice, range:1-Number of WANConnectionDevice.. - * EthernetLinkStatus: OUT. The status of the WNA Ethernet link. - * - * Description: - * Get the link status of the Ethernet connection specified by the input device index - * Related UPnP Device/Service: WANEthernetLinkConfigService - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ -// The valid value of the output parameter,"status" + +// The valid value of the output parameter,"status" #define ETHERNETLINKSTATUS_UP "Up" #define ETHERNETLINKSTATUS_DOWN "Down" #define ETHERNETLINKSTATUS_UNAVAILABLE "Unavailable" + +/** +* @brief Get Ethernet link status. +* +* Retrieves the link status of the WAN Ethernet connection. +* \n Reads WAN connection status from Utopia contex and returns "Up" if phylink_up is non-zero, "Down" otherwise. +* \n Related UPnP Device/Service: WANEthernetLinkConfigService. +* +* @param[in] WanDeviceIndex - Index of WANDevice, range: 1 to Number of WANDevices. +* @param[in] WanConnectionDeviceIndex - Index of WANConnectionDevice, range: 1 to Number of WANConnectionDevices. +* @param[out] EthernetLinkStatus - Buffer to store Ethernet link status string. +* \n Buffer should be allocated with at least 16 bytes. +* \n Values: ETHERNETLINKSTATUS_UP, ETHERNETLINKSTATUS_DOWN, ETHERNETLINKSTATUS_UNAVAILABLE. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval 1 if error retrieving WAN connection status from Utopia. +* +*/ extern INT32 IGD_pii_get_ethernet_link_status(IN INT32 WanDeviceIndex, IN INT32 WanConnectionDeviceIndex, OUT CHAR *EthernetLinkStatus); - -/************************************************************ - * Function: IGD_pii_get_common_link_properties - * - * Parameters: - * WanDeviceIndex: IN. Index of WANDevice, range:1-Number of WANDevice. - * WanAccessType: OUT. The type of the WAN access. - * Layer1UpstreamMaxBitRate: OUT. The MAX upstream theoretical bit rate(in bit/s) for the WAN device. - * Layer1DownstreamMaxBitRate: OUT. The MAX downstream theoretical bit rate(in bit/s) for the WAN device. - * PhyscialLinkStatus: OUT. The state of the physical connection(link) from WANDevice to a connected entity. - * - * Description: - * Get the common link properties of the WAN device specified by the input device index. - * Related UPnP Device/Service: WANCommonInterfaceConfigService - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ -// The valid value of the output parameter,"WanAccessType" -#define WANACCESSTYPE_DSL "DSL" + +// The valid value of the output parameter,"WanAccessType" +#define WANACCESSTYPE_DSL "DSL" #define WANACCESSTYPE_POTS "POTS" #define WANACCESSTYPE_CABLE "Cable" #define WANACCESSTYPE_ETHERNET "Ethernet" -// The valid value of the output parameter,"PhyscialLinkStatus" +// The valid value of the output parameter,"PhyscialLinkStatus" #define LINKSTATUS_UP "Up" #define LINKSTATUS_DOWN "Down" +/** +* @brief Get common link properties of WAN device. +* +* Retrieves common link properties including WAN access type, maximum bitrates, and physical link status +* specified by the input device index. +* \n Related UPnP Device/Service: WANCommonInterfaceConfigService. +* +* @param[in] WanDeviceIndex - Index of WANDevice, range: 1 to Number of WANDevices. +* @param[out] WanAccessType - Buffer to store WAN access type string. +* \n Buffer should be allocated with at least 16 bytes. +* \n Values: WANACCESSTYPE_DSL, WANACCESSTYPE_POTS, WANACCESSTYPE_CABLE, WANACCESSTYPE_ETHERNET. +* @param[out] Layer1UpstreamMaxBitRate - Buffer to store maximum upstream bitrate in bits per second. +* \n Buffer should be allocated with at least 16 bytes. +* @param[out] Layer1DownstreamMaxBitRate - Buffer to store maximum downstream bitrate in bits per second. +* \n Buffer should be allocated with at least 16 bytes. +* @param[out] PhyscialLinkStatus - Buffer to store physical link status string. +* \n Buffer should be allocated with at least 16 bytes. +* \n Values: LINKSTATUS_UP or LINKSTATUS_DOWN. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval 1 if error retrieving WAN connection status from Utopia. +* +*/ extern INT32 IGD_pii_get_common_link_properties(IN INT32 WanDeviceIndex, OUT CHAR *WanAccessType, OUT CHAR *Layer1UpstreamMaxBitRate, OUT CHAR *Layer1DownstreamMaxBitRate, OUT CHAR *PhyscialLinkStatus); - - - - -/************************************************************ - * Function: IGD_pii_get_traffic_stats - * - * Parameters: - * WanDeviceIndex: IN. Index of WANDevice, range:1-Number of WANDevice. - * bufsz: IN. size of output buffer (same for all four params) - * TotalBytesSent: OUT. Total bytes sent on the WAN device. - * TotalBytesReceived: OUT. Total bytes received on the WAN device. - * TotalPacketsSent: OUT. Total packets sent on the WAN device. - * TotalPacketsReceived: OUT. Total packets received on the WAN device. - * - * Description: - * Get the traffice statistics of the WAN device specified by the input device index. - * Related UPnP Device/Service: WANCommonInterfaceConfigService - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ +/** +* @brief Get WAN device traffic statistics. +* +* Retrieves traffic statistics including total bytes and packets sent/received on the WAN device +* specified by the input device index. +* \n Related UPnP Device/Service: WANCommonInterfaceConfigService. +* +* @param[in] WanDeviceIndex - Index of WANDevice, range: 1 to Number of WANDevices. +* @param[in] bufsz - Size of output buffers for all four output parameters (all buffers must be same size). +* @param[out] TotalBytesSent - Buffer to store total bytes sent on WAN device. +* \n Buffer should be allocated with size specified by bufsz parameter. +* @param[out] TotalBytesReceived - Buffer to store total bytes received on WAN device. +* \n Buffer should be allocated with size specified by bufsz parameter. +* @param[out] TotalPacketsSent - Buffer to store total packets sent on WAN device. +* \n Buffer should be allocated with size specified by bufsz parameter. +* @param[out] TotalPacketsReceived - Buffer to store total packets received on WAN device. +* \n Buffer should be allocated with size specified by bufsz parameter. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval 1 if error retrieving WAN traffic statistics. +* +*/ INT32 IGD_pii_get_traffic_stats(IN INT32 WanDeviceIndex, IN INT32 bufsz, OUT CHAR *TotalBytesSent, @@ -749,102 +810,123 @@ INT32 IGD_pii_get_traffic_stats(IN INT32 WanDeviceIndex, OUT CHAR *TotalPacketsSent, OUT CHAR *TotalPacketsReceived); -/************************************************************ - * Function: IGD_pii_get_lan_dhcpserver_configurable - * Parameters: - * LanDeviceIndex: IN. Index of LANDevice, range:1-Number of LANDevice. - * status: OUT. status - * - * Description: - * It is security violation to allow DHCP Server to be configurable using UPnP IGD - * currently there is no authentication to protect DHCP server set methods. - * hence return NOT configurable - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ +/** +* @brief Get LAN DHCP server configurability status. +* +* Returns whether the DHCP server is configurable via UPnP IGD. +* \n It is security violation to allow DHCP Server to be configurable using UPnP IGD currently +* there is no authentication to protect DHCP server set methods hence return NOT configurable +* +* @param[in] LanDeviceIndex - Index of LANDevice, range: 1 to Number of LANDevices. +* @param[out] status - Buffer to store configurability status. +* \n Buffer should be allocated with at least 16 bytes. +* \n Always returns "0" (not configurable). +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval Non-zero error code if failure. +* +*/ INT32 IGD_pii_get_lan_dhcpserver_configurable(IN INT32 LanDeviceIndex, OUT CHAR *status); -/************************************************************ - * Function: IGD_pii_get_lan_dhcp_relay - * Parameters: - * LanDeviceIndex: IN. Index of LANDevice, range:1-Number of LANDevice. - * status: OUT. status - * - * Description: - * Checks if we are in bridge mode, if yes return 1 - * if we are in router mode return 0 - * to be enhanced as part of LAN Auto-Bridging feature - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ +/** +* @brief Get LAN DHCP relay status. +* +* Checks if the device is in bridge mode (DHCP relay) or router mode. +* \n Checks if bridge mode, then return 1 and if router mode, then return 0 +* \n To be enhanced as part of LAN Auto-Bridging feature. +* +* @param[in] LanDeviceIndex - Index of LANDevice, range: 1 to Number of LANDevices. +* @param[out] status - Buffer to store DHCP relay status. +* \n Buffer should be allocated with at least 16 bytes. +* \n Returns "1" if bridge mode (DHCP relay), "0" if router mode. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval Non-zero error code if failure. +* +*/ INT32 IGD_pii_get_lan_dhcp_relay_status(IN INT32 LanDeviceIndex, OUT CHAR *status); -/************************************************************ - * Function: IGD_pii_get_lan_info - * Parameters: - * LanDeviceIndex: IN. Index of LANDevice, range:1-Number of LANDevice. - * bufsz: IN. buffer size of OUT params (they are all need to be same size) - * ipaddr: OUT. IP address of the LAN device - * subnet_mask: OUT. subnet mask address of the device - * domai_name: OUT. domain name of the device - * - * Description: - * Returns various LAN Device settings - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ +/** +* @brief Get LAN device information. +* +* Retrieves LAN device settings including IP address, subnet mask, and domain name. +* \n Reads LAN settings from Utopia context . +* +* @param[in] LanDeviceIndex - Index of LANDevice, range: 1 to Number of LANDevices. +* @param[in] bufsz - Size of output buffers for all three output parameters (all buffers must be same size). +* @param[out] ipaddr - Buffer to store LAN IP address +* \n Buffer should be allocated with size specified by bufsz parameter. +* @param[out] subnet_mask - Buffer to store subnet mask address. +* \n Buffer should be allocated with size specified by bufsz parameter. +* @param[out] domain_name - Buffer to store domain name of the device. +* \n Buffer should be allocated with size specified by bufsz parameter. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval 1 if error retrieving LAN settings from Utopia. +* +*/ INT32 IGD_pii_get_lan_info(IN INT32 LanDeviceIndex, IN INT32 bufsz, OUT CHAR *ipaddr, OUT CHAR *subnet_mask, OUT CHAR *domain_name); -/************************************************************ - * Function: IGD_pii_get_lan_dns_servers - * Parameters: - * LanDeviceIndex: IN. Index of LANDevice, range:1-Number of LANDevice. - * max_list_sz: IN. buffer size of OUT params (they are all need to be same size) - * dns_servers: OUT. comma separated list of dns servers - * - * Description: - * Returns various LAN DNS Servers - * Currently system uses router's dns proxy as the LAN's dns server, - * so just return LAN default gw address as the DNS server address - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ +/** +* @brief Get LAN DNS servers. +* +* Retrieves the list of DNS servers for the LAN device. +* \n Currently system uses router's DNS proxy as the LAN's DNS server, +* \n so returns LAN default gateway address (router IP) as the DNS server address. +* +* @param[in] LanDeviceIndex - Index of LANDevice, range: 1 to Number of LANDevices. +* @param[out] dns_servers - Buffer to store comma-separated list of DNS server addresses. +* \n Buffer should be allocated with size specified by max_list_sz parameter. +* @param[in] max_list_sz - Maximum size of dns_servers buffer. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval 1 if error retrieving LAN settings from Utopia. +* +*/ INT32 IGD_pii_get_lan_dns_servers(IN INT32 LanDeviceIndex, OUT CHAR *dns_servers, IN INT32 max_list_sz); -/************************************************************ - * Function: IGD_pii_get_lan_addr_range - * Parameters: - * LanDeviceIndex: IN. Index of LANDevice, range:1-Number of LANDevice. - * buf_sz: IN. buffer size of OUT params (they are all need to be same size) - * min_address: OUT. start address of the range - * max_address: OUT. end address of the range - * - * Description: - * Returns various LAN DHCP Server's DHCP address range - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ +/** +* @brief Get LAN DHCP address range. +* +* Retrieves the DHCP address range (minimum and maximum addresses) for the LAN DHCP server. +* \n Reads DHCP server settings and LAN settings from Utopia context. +* \n Calculates range using LAN IP subnet and DHCP server's DHCPIPAddressStart and DHCPMaxUsers. +* +* @param[in] LanDeviceIndex - Index of LANDevice, range: 1 to Number of LANDevices. +* @param[in] buf_sz - Size of output buffers for both output parameters (both buffers must be same size). +* @param[out] min_address - Buffer to store start address of DHCP range. +* \n Buffer should be allocated with size specified by buf_sz parameter. +* @param[out] max_address - Buffer to store end address of DHCP range. +* \n Buffer should be allocated with size specified by buf_sz parameter. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval 1 if error retrieving DHCP server or LAN settings from Utopia. +* +*/ INT32 IGD_pii_get_lan_addr_range(IN INT32 LanDeviceIndex, IN INT32 buf_sz, OUT CHAR *min_address, OUT CHAR *max_address); -/************************************************************ - * Function: IGD_pii_get_lan_reserved_addr_list - * Parameters: - * LanDeviceIndex: IN. Index of LANDevice, range:1-Number of LANDevice. - * max_list_sz: IN. buffer size of OUT params (they are all need to be same size) - * reserved_list: OUT. comma separated list of reserved DHCP addresses - * - * Description: - * Returns LAN DHCP Server's reserverd DHCP addresses - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ +/** +* @brief Get LAN reserved DHCP address list. +* +* Retrieves the list of reserved DHCP addresses (static host mappings) configured on the LAN DHCP server. +* \n Reads LAN settings and DHCP static hosts from Utopia context. +* \n Returns comma-separated list of IP addresses that have static DHCP reservations. +* +* @param[in] LanDeviceIndex - Index of LANDevice, range: 1 to Number of LANDevices. +* @param[out] reserved_list - Buffer to store comma-separated list of reserved DHCP IP addresses. +* \n Buffer should be allocated with size specified by max_list_sz parameter. +* @param[in] max_list_sz - Maximum size of reserved_list buffer. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval 1 if error retrieving LAN settings or DHCP static hosts from Utopia. +* +*/ INT32 IGD_pii_get_lan_reserved_addr_list(IN INT32 LanDeviceIndex, OUT CHAR *reserved_list, IN INT32 max_list_sz); -#endif /*IGD_PLATFORM_INDEPENDENT_INF_H*/ - +#endif /*IGD_PLATFORM_INDEPENDENT_INF_H*/ \ No newline at end of file diff --git a/source/igd/src/inc/igd_service_wan_connect.h b/source/igd/src/inc/igd_service_wan_connect.h index d1aa104f..bd702580 100644 --- a/source/igd/src/inc/igd_service_wan_connect.h +++ b/source/igd/src/inc/igd_service_wan_connect.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -33,7 +33,7 @@ limitations under the License. **********************************************************************/ -/* +/* * FileName: igd_service_wan_connect.h * Author: Andy Liu(zhihliu@cisco.com) * Tao Hong(tahong@cisco.com) @@ -102,31 +102,39 @@ typedef struct{ CHAR *desc; } error_pair; -/************************************************************ -* Function: IGD_wan_ppp_connection_service_init +/** +* @brief Initialize WAN IP connection service instance. +* +* Creates and initializes a WANIPConnection service instance for the UPnP IGD device. +* \n Called by IGD_wan_connection_device_init() to initialize a wan ip connection service instance. * -* Parameters: -* input_index_struct: IN. Wan device index, wan connection device index and wan connection service index -* wan_desc_file: INOUT. The fd to write description file -* Description: -* This function is called by IGD_wan_connection_device_init() to initialize a wan ppp connection service instance +* @param[in] input_index_struct - Pointer to device_and_service_index structure containing: +* \n WAN device index, WAN connection device index, and WAN connection service index. +* @param[in,out] wan_desc_file - File pointer to device description file for writing service XML entry. +* \n Service description will be appended to this file. * -* Return Values: struct upnp_service * -* the initialized wan ppp connection service if successful else NULL -************************************************************/ +* @return Pointer to initialized upnp_service structure. +* @retval struct upnp_service* - Pointer to initialized WAN IP connection service if successful. +* @retval NULL if initialization fails (memory allocation error or invalid parameters). +* +*/ extern struct upnp_service * IGD_wan_ip_connection_service_init (IN VOID* input_index_struct, INOUT FILE *wan_desc_file); -/************************************************************ -* Function: IGD_wan_ip_connection_service_init +/** +* @brief Initialize WAN PPP connection service instance. +* +* Creates and initializes a WANPPPConnection service instance for the UPnP IGD device. +* \n Called by IGD_wan_connection_device_init() to initialize a wan ppp connection service instance. * -* Parameters: -* input_index_struct: IN. Wan device index, wan connection device index and wan connection service index -* wan_desc_file: INOUT. The fd to write description file -* Description: -* This function is called by IGD_wan_connection_device_init() to initialize a wan ip connection service instance +* @param[in] input_index_struct - Pointer to device_and_service_index structure containing: +* \n WAN device index, WAN connection device index, and WAN connection service index. +* @param[in,out] wan_desc_file - File pointer to device description file for writing service XML entry. +* \n Service description will be appended to this file. * -* Return Values: struct upnp_service * -* the initialized wan ip connection service if successful else NULL -************************************************************/ +* @return Pointer to initialized upnp_service structure. +* @retval struct upnp_service* - Pointer to initialized WAN PPP connection service if successful. +* @retval NULL if initialization fails (memory allocation error or invalid parameters). +* +*/ extern struct upnp_service * IGD_wan_ppp_connection_service_init (IN VOID* input_index_struct, INOUT FILE *wan_desc_file); #endif /* WAN_CONNECTION_SERVICE_H */ diff --git a/source/igd/src/inc/igd_utility.h b/source/igd/src/inc/igd_utility.h index b803b897..c9ab26e7 100644 --- a/source/igd/src/inc/igd_utility.h +++ b/source/igd/src/inc/igd_utility.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -33,7 +33,7 @@ limitations under the License. **********************************************************************/ -/* +/* * FileName: wan_connection_device_internal.h * Author: Tao Hong(tahong@cisco.com) * Date: 2009-05-03 @@ -81,10 +81,10 @@ p=NULL;} struct device_and_service_index{ - INT32 wan_device_index; //begin from 1 - INT32 wan_connection_device_index; //begin from 1 + INT32 wan_device_index; //begin from 1 + INT32 wan_connection_device_index; //begin from 1 INT32 wan_connection_service_index; //begin from 1 - INT32 lan_device_index; //begin from 1 + INT32 lan_device_index; //begin from 1 }; //for timer @@ -107,13 +107,59 @@ struct timer_function_node struct timer_function_node* next; }; +/** + * @brief Start the IGD timer mechanism. + * + * This function initializes and starts two timer threads (timer_thread_id_run_once and timer_thread_id_cycle) + * for managing run-once and cyclic timer callbacks. It initializes the necessary mutexes and creates detached + * threads for timer processing. The function ensures thread safety and proper initialization of the timer system. + * + * @return None + */ extern VOID IGD_timer_start(VOID); +/** + * @brief Stop the IGD timer mechanism. + * + * This function stops the two timer threads (timer_thread_id_run_once and timer_thread_id_cycle) and + * destroys the associated mutexes. It cancels the running timer threads and cleans up the timer system resources. + * + * @return None + */ extern VOID IGD_timer_stop(VOID); +/** + * @brief Register a timer callback function with the IGD timer mechanism. + * + * This function registers a timer callback function to be executed either once or cyclically based on the + * specified mode. The callback is associated with a UPnP device and service context, and will be triggered + * after the specified time interval. The function is added to either the run-once or cyclic timer list + * depending on the mode parameter. + * + * @param[in] input_upnp_device - Pointer to the UPnP device structure associated with the timer callback + * @param[in] input_upnp_service - Pointer to the UPnP service structure associated with the timer callback + * @param[in] input_timer_function - Pointer to the timer callback function to be executed + * @param[in] input_trigger_second - Time interval in seconds for the timer trigger (must be greater than 0) + * @param[in] input_mode - Timer execution mode (timer_function_mode_run_once or timer_function_mode_cycle) + * + * @return None + */ extern VOID IGD_timer_register(IN struct upnp_device * input_upnp_device, IN struct upnp_service * input_upnp_service, IN timer_function_t input_timer_function, IN INT32 input_trigger_second, IN INT32 input_mode); +/** + * @brief Check if the internal client address is valid for port mapping. + * + * This function validates whether the specified client IP address is valid for port mapping operations. + * It retrieves the LAN settings and checks if the client address is on the same network, is not the + * gateway address itself, and is not a broadcast or network address. + * + * @param[in] client - String representation of the internal client IP address to validate + * + * @return Status of internal client address + * @retval TRUE - Client address is valid for port mapping + * @retval FALSE - Client address is invalid (same as gateway, broadcast, network address, or not on same subnet) + */ extern BOOL chkPortMappingClient(char* client); #endif /*WAN_CONNECTION_DEVICE_INTERNAL_H*/ diff --git a/source/include/service_multinet/service_multinet_ep.h b/source/include/service_multinet/service_multinet_ep.h index 64bc1165..f0c67480 100644 --- a/source/include/service_multinet/service_multinet_ep.h +++ b/source/include/service_multinet/service_multinet_ep.h @@ -18,20 +18,20 @@ */ /********************************************************************** Copyright [2015] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. **********************************************************************/ -#ifndef MNET_EP_H +#ifndef MNET_EP_H #define MNET_EP_H #include "service_multinet_base.h" @@ -43,29 +43,136 @@ #define MNET_EP_BRIDGE_NAME_FORMAT(instance) "multinet_%d-name", instance #define MNET_EP_BRIDGE_MODE_KEY "bridge_mode" -//int ep_set_memberStatus(PL2Net net, PMember member); +//int ep_set_memberStatus(PL2Net net, PMember member); +/** +* @brief Get all member interfaces of a Layer 2 network. +* +* @param[in] net - Pointer to the L2Net structure representing the Layer 2 network. +* @param[out] live_members - Pointer to the array of Member structures to store retrieved members. +* @param[in] numMembers - Maximum number of members that can be stored in the live_members array. +* +* @return The actual number of members retrieved. +* +*/ int ep_get_allMembers(PL2Net net, PMember live_members, int numMembers); + +/** +* @brief Set all member interfaces for a Layer 2 network. +* +* @param[in] net - Pointer to the L2Net structure representing the Layer 2 network. +* @param[in] members - Pointer to the array of Member structures to be set. +* @param[in] numMembers - Number of members in the members array. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int ep_set_allMembers(PL2Net net, PMember members, int numMembers); +/** +* @brief Clear all members and configuration for a Layer 2 network. +* +* @param[in] net - Pointer to the L2Net structure representing the Layer 2 network to clear. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int ep_clear(PL2Net net); // TODO +/** +* @brief Add a Layer 2 network to the active networks list. +* +* @param[in] net - Pointer to the L2Net structure representing the Layer 2 network to add. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int ep_add_active_net(PL2Net net); // TODO deferred + +/** +* @brief Remove a Layer 2 network from the active networks list. +* +* @param[in] net - Pointer to the L2Net structure representing the Layer 2 network to remove. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int ep_rem_active_net(PL2Net net); // TODO deferred +/** +* @brief Check if a Layer 2 network instance is started. +* +* @param[in] netInst - The Layer 2 network instance identifier. +* +* @return The network started status. +* @retval Non-zero if the network is started. +* @retval 0 if the network is not started. +* +*/ int ep_netIsStarted(int netInst); // TODO -int ep_get_bridge(int l2netinst, PL2Net net); +/** +* @brief Get bridge configuration for a Layer 2 network instance. +* +* @param[in] l2netinst - The Layer 2 network instance identifier. +* @param[out] net - Pointer to the L2Net structure to store the bridge configuration. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ +int ep_get_bridge(int l2netinst, PL2Net net); + +/** +* @brief Set bridge configuration for a Layer 2 network. +* +* @param[in] net - Pointer to the L2Net structure containing the bridge configuration to set. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int ep_set_bridge(PL2Net net); +/** +* @brief Get the current bridge mode setting. +* +* @return The bridge mode value. +* +*/ int ep_get_bridge_mode(void); //-- Raw +/** +* @brief Set a raw string value for a specified key. +* +* @param[in] key - Pointer to the key string. +* @param[in] value - Pointer to the value string to set. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int ep_set_rawString(char* key, char* value); -int ep_get_rawString(char* key, char* value, int valueSize); +/** +* @brief Get a raw string value for a specified key. +* +* @param[in] key - Pointer to the key string. +* @param[out] value - Pointer to the buffer to store the retrieved value string. +* @param[in] valueSize - Size of the value buffer in bytes. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ +int ep_get_rawString(char* key, char* value, int valueSize); -#endif +#endif \ No newline at end of file diff --git a/source/include/service_multinet/service_multinet_ev.h b/source/include/service_multinet/service_multinet_ev.h index 4261a50b..59a4fe9b 100644 --- a/source/include/service_multinet/service_multinet_ev.h +++ b/source/include/service_multinet/service_multinet_ev.h @@ -18,13 +18,13 @@ */ /********************************************************************** Copyright [2015] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -47,33 +47,94 @@ extern token_t sysevent_token_interactive; extern int sysevent_fd_interactive; /** - * Register the current running process for the given interface event name. If a status value name - * and bool pointer are provided, the current status will be polled after registration and filled into - * the bool variable to handle any registration / initialization race conditions. - * - * This function must register in the appropriate way based on execution style of the process. - */ -int ev_register_ifstatus(PL2Net net, PMember member, char* ifStatusEventName, char* ifStatusValueName, BOOL* readyFlag); +* @brief Register the current running process for the given interface event name. +* +* This function must register in the appropriate way based on execution style of the process. +* If a status value name and bool pointer are provided, the current status will be polled after +* registration and filled into the bool variable to handle any registration / initialization race conditions. +* +* @param[in] net - Pointer to the L2Net structure representing the Layer 2 network. +* @param[in] member - Pointer to the Member structure representing the network member. +* @param[in] ifStatusEventName - Pointer to the interface status event name string. +* @param[in] ifStatusValueName - Pointer to the interface status value name string (optional). +* @param[out] readyFlag - Pointer to the BOOL variable to store the current status after registration. +* \n If provided, the current status will be polled after registration to handle any registration/initialization race conditions. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ +int ev_register_ifstatus(PL2Net net, PMember member, char* ifStatusEventName, char* ifStatusValueName, BOOL* readyFlag); -/** - * Unregister the current running process for the given interface event name. - */ -int ev_unregister_ifstatus(PL2Net net, char* ifStatusEventName); +/** +* @brief Unregister the current running process for the given interface event name. +* +* @param[in] net - Pointer to the L2Net structure representing the Layer 2 network. +* @param[in] ifStatusEventName - Pointer to the interface status event name string. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ +int ev_unregister_ifstatus(PL2Net net, char* ifStatusEventName); -/** - * Announce to the system the status of a given l2net. - */ -int ev_set_netStatus(PL2Net net, enum service_status status); +/** +* @brief Announce to the system the status of a given Layer 2 network. +* +* @param[in] net - Pointer to the L2Net structure representing the Layer 2 network. +* @param[in] status - The service status to set. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ +int ev_set_netStatus(PL2Net net, enum service_status status); -/** Initialize the event system. isDaemon should be initialized before this is called. - */ -int ev_init(void); +/** +* @brief Initialize the event system. +* +* This function initialize the event system. isDaemon should be initialized before this is called. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval -1 on error. +* +*/ +int ev_init(void); +/** +* @brief Convert a status string to SERVICE_STATUS enumeration. +* +* @param[in] stringStatus - Pointer to the status string to convert. +* @param[out] status - Pointer to store the converted SERVICE_STATUS value. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int ev_string_to_status(char* stringStatus, SERVICE_STATUS* status); +/** +* @brief Trigger a firewall restart event. +* +* this function used for ev firewall restart Triggering. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int ev_firewall_restart(void); +/** +* @brief Set the name event for a Layer 2 network. +* +* @param[in] net - Pointer to the L2Net structure representing the Layer 2 network. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int ev_set_name(PL2Net net); //Private---------- @@ -81,7 +142,7 @@ int ev_set_name(PL2Net net); /** This function registers the current handler for the specified event. Function must register * appropriately based on the calling style of the handler and capabilities of the underlying eventing * system. Calling style should be indicated during lib init. - */ -//int ev_register_event(char* eventName); + */ +//int ev_register_event(char* eventName); -#endif +#endif \ No newline at end of file diff --git a/source/include/service_multinet/service_multinet_handler.h b/source/include/service_multinet/service_multinet_handler.h index 7d98bcd5..bb276208 100644 --- a/source/include/service_multinet/service_multinet_handler.h +++ b/source/include/service_multinet/service_multinet_handler.h @@ -18,13 +18,13 @@ */ /********************************************************************** Copyright [2015] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -64,20 +64,82 @@ struct allIfHandlers { #ifdef MULTINET_IFHANDLER_PLUGIN MemberHandler pluginHandlers[NUM_PLUGIN_IFTYPES]; #endif - + MemberHandler defaultHandlers[NUM_DEFAULT_IFTYPES]; - + }; extern PMemberHandler handlerList; extern int numHandlers; +/** +* @brief Initialize the interface handler system. +* +* This function initializes the global handler list by registering default handlers. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int handlerInit(); +/** +* @brief Create and register interfaces for a Layer 2 network. +* +* This function performs interface creation and registration for all applicable handlers +* and registers dynamic interfaces for status events. +* +* @param[in] net - Pointer to the L2Net structure representing the Layer 2 network. +* @param[in] members - Pointer to the array of Member structures to create and register. +* @param[in] numMembers - Number of members in the members array. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int create_and_register_if(PL2Net net, PMember members, int numMembers); +/** +* @brief Unregister interfaces from a Layer 2 network. +* +* This function performs cleanup of mappings and unregisters dynamic interfaces from the event system. +* +* @param[in] net - Pointer to the L2Net structure representing the Layer 2 network. +* @param[in] members - Pointer to the array of Member structures to unregister. +* @param[in] numMembers - Number of members in the members array. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int unregister_if(PL2Net net, PMember members, int numMembers); +/** +* @brief Add VLAN tagging for member interfaces. +* +* This function adds VLAN tagging to member interfaces by invoking the appropriate handler-specific implementation. +* +* @param[in] net - Pointer to the L2Net structure representing the Layer 2 network. +* @param[in] members - Pointer to the array of Member structures to add VLAN for. +* @param[in] numMembers - Number of members in the members array. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int add_vlan_for_members(PL2Net net, PMember members, int numMembers); +/** +* @brief Remove VLAN tagging from member interfaces. +* +* This function removes VLAN tagging from member interfaces by invoking the appropriate handler-specific implementation. +* +* @param[in] net - Pointer to the L2Net structure representing the Layer 2 network. +* @param[in] members - Pointer to the array of Member structures to remove VLAN from. +* @param[in] numMembers - Number of members in the members array. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int remove_vlan_for_members(PL2Net net, PMember members, int numMembers); -#endif +#endif \ No newline at end of file diff --git a/source/include/service_multinet/service_multinet_lib.h b/source/include/service_multinet/service_multinet_lib.h index 106fec0b..722243d1 100644 --- a/source/include/service_multinet/service_multinet_lib.h +++ b/source/include/service_multinet/service_multinet_lib.h @@ -18,13 +18,13 @@ */ /********************************************************************** Copyright [2015] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -33,13 +33,13 @@ **********************************************************************/ #ifndef MNET_LIB_H #define MNET_LIB_H - + #include "service_multinet_base.h" #include - + #define MAX_MEMBERS 32 - + #if defined (INTEL_PUMA7) || defined(MULTILAN_FEATURE) //Intel Proposed RDKB Bug Fix #define MAX_BUF_SIZE 256 @@ -51,38 +51,187 @@ #define STATUS_NOK 1 #endif #endif //defined (INTEL_PUMA7) - + extern unsigned char isDaemon; extern char* executableName; - + extern bool ethWanEnableState; +/** +* @brief Bring up a Layer 2 network bridge. +* +* This function load the stored configuration and initialize the bridge network. +* +* @param[in] network - Pointer to the L2Net structure representing the Layer 2 network. +* @param[in] bFirewallRestart - Flag indicating whether to restart the firewall. +* \n Non-zero value triggers firewall restart. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int multinet_bridgeUp(PL2Net network, int bFirewallRestart); + + /** +* @brief Bring up a Layer 2 network bridge by instance identifier. +* +* This function uses the network instance ID to load the stored configuration and initialize the bridge network. +* +* @param[in] l2netInst - The Layer 2 network instance identifier. +* @param[in] bFirewallRestart - Flag indicating whether to restart the firewall. +* \n Non-zero value triggers firewall restart. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int multinet_bridgeUpInst(int l2netInst, int bFirewallRestart); - + +/** +* @brief Bring down a Layer 2 network bridge. +* +* @param[in] network - Pointer to the L2Net structure representing the Layer 2 network. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int multinet_bridgeDown(PL2Net network); + + /** +* @brief Bring down a Layer 2 network bridge by instance identifier. +* +* @param[in] l2netInst - The Layer 2 network instance identifier. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int multinet_bridgeDownInst(int l2netInst); - + +/** +* @brief Synchronize a Layer 2 network with specified member interfaces. +* +* @param[in] network - Pointer to the L2Net structure representing the Layer 2 network. +* @param[in] members - Pointer to the array of Member structures to synchronize. +* @param[in] numMembers - Number of members in the members array. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int multinet_Sync(PL2Net network, PMember members, int numMembers); + + /** +* @brief Synchronize a Layer 2 network by instance identifier. +* +* @param[in] l2netInst - The Layer 2 network instance identifier. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int multinet_SyncInst(int l2netInst); - + +/** +* @brief Synchronize all Layer 2 network bridges in the system. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int multinet_bridgesSync(); - + +/** +* @brief Update the interface status for a member in a Layer 2 network. +* +* @param[in] network - Pointer to the L2Net structure representing the Layer 2 network. +* @param[in] interface - Pointer to the Member structure representing the interface. +* @param[in] status - The interface status to set. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int multinet_ifStatusUpdate(PL2Net network, PMember interface, IF_STATUS status); + + /** +* @brief Update the interface status using identifier strings. +* +* @param[in] l2netInst - The Layer 2 network instance identifier. +* @param[in] ifname - Pointer to the interface name string. +* @param[in] ifType - Pointer to the interface type string. +* @param[in] status - Pointer to the status string. +* @param[in] tagging - Pointer to the VLAN tagging configuration string. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int multinet_ifStatusUpdate_ids(int l2netInst, char* ifname, char* ifType, char* status, char* tagging); - + +/** +* @brief Initialize the multinet library. +* +* @param[in] daemon - Flag indicating whether running as a daemon (TRUE) or not (FALSE). +* @param[in] exeName - Pointer to the executable name string. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int multinet_lib_init(BOOL daemon, char* exeName); - + #if defined (INTEL_PUMA7) || defined(MULTILAN_FEATURE) //Intel Proposed RDKB Bug Fix +/** +* @brief Get the interface name from the port name. +* +* Get the interface name from the port name. ifName would be the real interface name +* if it's not switch port. Otherwise, ifName would be same as port name. + +* @param[out] ifName - Pointer to the buffer to store the interface name string. +* @param[in] portName - Pointer to the port name string. +* +* @return The status of the operation. +* @retval STATUS_OK on success. +* @retval STATUS_NOK on failure. +* +*/ int getIfName(char *ifName, char* portName); + #endif #if defined(MULTILAN_FEATURE) +/** +* @brief Assign a CIDR block to a bridge for a Layer 2 network instance. +* +* This function assign an address in CIDR format to a bridge instance. +* +* @param[in] l2netInst - The Layer 2 network instance identifier. +* @param[in] CIDR - Pointer to the CIDR notation string. +* @param[in] IPVersion - IP version type. +* \n Value 4 for IPv4 or 6 for IPv6. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int multinet_assignBridgeCIDR(int l2netInst, char *CIDR, int IPVersion); -#endif + + #endif #if defined(MESH_ETH_BHAUL) +/** +* @brief Toggle Ethernet backhaul ports on or off. +* +* @param[in] onOff - Boolean flag to enable (TRUE) or disable (FALSE) Ethernet backhaul ports. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int toggle_ethbhaul_ports(BOOL onOff); + #endif - - #endif + + #endif \ No newline at end of file diff --git a/source/include/service_multinet/service_multinet_nv.h b/source/include/service_multinet/service_multinet_nv.h index 648c73f7..10dc0fe1 100644 --- a/source/include/service_multinet/service_multinet_nv.h +++ b/source/include/service_multinet/service_multinet_nv.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2015] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -41,10 +41,48 @@ #include "service_multinet_base.h" +/** +* @brief Get member interfaces from non-volatile storage for a Layer 2 network. +* +* @param[in] net - Pointer to the L2Net structure representing the Layer 2 network. +* @param[out] memberList - Pointer to the array of Member structures to store retrieved members. +* @param[in] numMembers - Maximum number of members that can be stored in the memberList array. +* +* @return The actual number of members retrieved. +* @retval number of members on success +* @retval 0 on failure +* +*/ int nv_get_members(PL2Net net, PMember memberList, int numMembers); +/** +* @brief Get bridge configuration from non-volatile storage for a Layer 2 network instance. +* +* @param[in] l2netInst - The Layer 2 network instance identifier. +* @param[out] net - Pointer to the L2Net structure to store the bridge configuration. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int nv_get_bridge(int l2netInst, PL2Net net); +/** +* @brief Get the primary Layer 2 network instance identifier from non-volatile storage. +* +* @return The primary Layer 2 network instance identifier. +* +*/ int nv_get_primary_l2_inst(void); #if defined(MESH_ETH_BHAUL) +/** +* @brief Toggle Ethernet backhaul ports on or off. +* +* @param[in] onOff - Boolean flag to enable (TRUE) or disable (FALSE) Ethernet backhaul ports. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval -1 on failure. +* +*/ int nv_toggle_ethbhaul_ports(BOOL onOff); #endif diff --git a/source/include/service_multinet/service_multinet_plat.h b/source/include/service_multinet/service_multinet_plat.h index a7781775..55a8c5cd 100644 --- a/source/include/service_multinet/service_multinet_plat.h +++ b/source/include/service_multinet/service_multinet_plat.h @@ -19,20 +19,20 @@ /********************************************************************** Copyright [2015] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. **********************************************************************/ - + #ifndef MNET_IFPLUG_H #define MNET_IFPLUG_H //Must define a header file called service_multinet_ifplugin_defs.h which @@ -41,16 +41,31 @@ //// #include "service_multinet_ifplugin_defs.h" #include "service_multinet_handler.h" #include "service_multinet_base.h" - + +/** +* @brief Add implicit member interfaces from platform configuration. +* +* @param[in] nv_net - Pointer to the L2Net structure from non-volatile storage. +* @param[out] memberBuf - Pointer to the Member buffer to store implicit members. +* +* @return The number of implicit members added. +* +*/ int plat_addImplicitMembers(PL2Net nv_net, PMember memberBuf); - + #ifdef MULTINET_IFHANDLER_PLUGIN - /**Fill 'handlers' with all required platform specific handlers - * for DM interfaces. See the MemberHandler definition for a - * list of functions that must be mapped for each handler. - */ +/** +* @brief Initialize platform-specific multinet plugin handlers. +* +* @param[out] handlers - Pointer to the allIfHandlers structure to fill with platform specific handlers. +* \n See the MemberHandler definition for required functions that must be mapped for each handler. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int mnet_plugin_init(struct allIfHandlers* handlers); #endif #endif - + diff --git a/source/include/service_multinet/service_multinet_swfab.h b/source/include/service_multinet/service_multinet_swfab.h index 411341ca..3a2ea7ed 100644 --- a/source/include/service_multinet/service_multinet_swfab.h +++ b/source/include/service_multinet/service_multinet_swfab.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2015] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -48,16 +48,16 @@ #define MAX_ENTITIES 32 #define MAX_PATHS 128 -typedef struct vidParams { +typedef struct vidParams { int vid; int tagging; int pvid; } VLANParams, *PVLANParams; - + typedef struct portConfig { struct platport* platPort; VLANParams vidParams; -} PortConfig, *PPortConfig; +} PortConfig, *PPortConfig; typedef struct pcControl { PortConfig config; @@ -74,7 +74,7 @@ typedef struct halArg { VLANParams vidParams; BOOL ready; HalHints hints; -} SWFabHALArg, *PSWFabHALArg; +} SWFabHALArg, *PSWFabHALArg; typedef struct argMemberMap { PSWFabHALArg args; @@ -91,15 +91,15 @@ typedef struct swfabhal { // Used to match. Should be unique for each instance, or initIF and configVlan should be // identical across instances. int id; - + //Should fill the 'ready' field of each member IFHandlerFunc initIF; - + IFHandlerFunc configVlan; - + //Check if two ports are equal. Do not assume all arguements are of the local HALs portID type. IsEqualFunc isEqual; - + /**Return the number of characters written including null terminator. */ IDToStringFunc stringID; @@ -115,12 +115,12 @@ typedef struct platport { * by the bridging framework. A false value here will save some overhead. */ int isDynamic; - - /** Shared means this port may be a trunking port for multiple other platform ports in - * some configuration. If it can be a shared pathway, mark this true. - * + + /** Shared means this port may be a trunking port for multiple other platform ports in + * some configuration. If it can be a shared pathway, mark this true. + * * The framework will force this port to tagging mode if this port is a dependency - * and this flag is set. Otherwise the port will be assigned the tagging mode specified + * and this flag is set. Otherwise the port will be assigned the tagging mode specified * on the member port. */ //int isShared; @@ -131,16 +131,87 @@ typedef struct platport { // typedef struct ifTypeHandler { -// +// // } IFTypeHandler, *PIFTypeHandler; +/** + * @brief Adds VLAN configuration to a Layer 2 network. + * + * This function adds VLAN configuration for the specified network and its member interfaces. + * It maps interfaces to platform ports, retrieves VLAN state, and configures trunk ports + * with proper VLAN tagging. This is a wrapper that calls swfab_configVlan with add flag set to 1. + * + * @param[in] net - Pointer to Layer 2 network structure containing network instance and VLAN ID. + * @param[in] members - Pointer to member control structure containing member interfaces and their states. + * + * @return Status of the operation. + * @retval 0 on success. + */ int swfab_addVlan(PL2Net net, PMemberControl members); + +/** + * @brief Removes VLAN configuration from a Layer 2 network. + * + * This function removes VLAN configuration for the specified network and its member interfaces. + * It removes interfaces from bridges, removes VLAN tags, and cleans up trunk port configurations. + * This is a wrapper that calls swfab_configVlan with add flag set to 0. + * + * @param[in] net - Pointer to Layer 2 network structure containing network instance and VLAN ID. + * @param[in] members - Pointer to member control structure containing member interfaces and their states. + * + * @return Status of the operation. + * @retval 0 on success. + */ int swfab_removeVlan(PL2Net net, PMemberControl members); + +/** + * @brief Creates and initializes a Layer 2 network with its member interfaces. + * + * This function performs initial creation of a Layer 2 network by mapping interfaces to platform ports + * and calling each HAL's initIF function to initialize interfaces. It groups interfaces by HAL type, + * calls the initialization function for each HAL only once, and propagates the ready flag from HAL + * responses back to member structures. + * + * @param[in] net - Pointer to Layer 2 network structure containing network instance information. + * @param[in,out] members - Pointer to member control structure. + * \n Input: Contains member interfaces to initialize. + * \n Output: Updates handled flags and bReady status for each member. + * + * @return Status of the operation. + * @retval 0 on success. + */ int swfab_create(PL2Net net, PMemberControl members); + +/** + * @brief Maps network interfaces to platform ports and marks them as handled. + * + * This function iterates through member interfaces and maps each unmapped interface to its + * corresponding platform port using mapToPlat. It also populates dynamic interface properties + * and event names, then marks interfaces as handled. + * + * @param[in] net - Pointer to Layer 2 network structure. + * @param[in,out] members - Pointer to member control structure. + * \n Input: Contains member interfaces to map. + * \n Output: Updates interface map pointers, dynamic flags, event names, and handled flags. + * + * @return Status of the operation. + * @retval 0 on success. + */ int swfab_domap(PL2Net net, PMemberControl members); //------------- //int isPortEqual(PPlatformPort portA, PPlatformPort portB); + +/** + * @brief Prints platform port information for debugging. + * + * This function retrieves the string identifier of a platform port using its HAL's stringID + * function and prints it for debugging purposes. It handles NULL port and missing HAL cases. + * + * @param[in] port - Pointer to platform port structure to print. + * + * @return None. + */ void printPlatport(PPlatformPort port); diff --git a/source/include/service_multinet/service_multinet_swfab_LinIF.h b/source/include/service_multinet/service_multinet_swfab_LinIF.h index 6dab8503..6546eccf 100644 --- a/source/include/service_multinet/service_multinet_swfab_LinIF.h +++ b/source/include/service_multinet/service_multinet_swfab_LinIF.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2015] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -37,7 +37,41 @@ #include "service_multinet_swfab.h" +/** + * @brief Configures VLAN settings for Linux network interfaces. + * + * This function adds or removes Linux network interfaces from bridge devices and configures + * VLAN tagging as needed. When bringing interfaces up, it creates VLAN interfaces using vconfig + * if tagging is enabled, adds interfaces to bridges using brctl, and brings interfaces up. + * When bringing interfaces down, it removes VLAN interfaces or removes interfaces from bridges. + * + * @param[in] args - Array of SWFabHALArg structures containing interface configuration. + * \n args[i].portID contains the interface name. + * \n args[i].vidParams.vid contains the VLAN ID. + * \n args[i].vidParams.tagging indicates if VLAN tagging is enabled. + * \n args[i].hints.network->name contains the bridge name. + * @param[in] numArgs - Number of arguments in the args array. + * @param[in] up - Boolean flag indicating operation mode. + * \n TRUE to bring interfaces up and add to bridge. + * \n FALSE to bring interfaces down and remove from bridge. + * + * @return Status of the operation. + * @retval 0 on success. + */ int linuxIfConfigVlan(PSWFabHALArg args, int numArgs, BOOL up); + +/** + * @brief Initializes Linux network interfaces. + * + * This function is to initialize the Linux network interfaces + * + * @param[in] args - Array of SWFabHALArg structures containing interface configuration. + * @param[in] numArgs - Number of arguments in the args array. + * @param[in] up - Boolean flag indicating whether to bring the interface up (TRUE) or down (FALSE). + * + * @return Status of the operation. + * @retval 0 on success. + */ int linuxIfInit(PSWFabHALArg args, int numArgs, BOOL up); #endif diff --git a/source/include/service_multinet/service_multinet_swfab_deps.h b/source/include/service_multinet/service_multinet_swfab_deps.h index 5eb48c21..83a01bd1 100644 --- a/source/include/service_multinet/service_multinet_swfab_deps.h +++ b/source/include/service_multinet/service_multinet_swfab_deps.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2015] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -68,53 +68,224 @@ typedef struct entityPathDeps { EntityPath path; int numPorts; PPlatformPort* trunkPorts; - + } EntityPathDeps, *PEntityPathDeps; //---- Public -/** Fills listToAppend with new trunk ports that should be configured (PPlatformPort) +/** + * @brief Adds a new port to a VLAN entity and retrieves trunk ports that need configuration. + * + * This function adds a new platform port to its associated entity within the VLAN state. + * If the entity does not exist, it creates the entity and calculates path dependencies to other entities, + * then populates the list with trunk ports that require configuration. Fills listToAppend with new trunk + * ports that should be configured (PPlatformPort). + * + * @param[in,out] vidState - Pointer to the VLAN trunk state structure. + * @param[in] newPort - Pointer to the platform port to be added. + * @param[out] listToAppend - Pointer to list where new trunk ports requiring configuration will be appended. + * + * @return The number of trunk ports that were changed/added. */ int addAndGetTrunkPorts(PVlanTrunkState vidState, PPlatformPort newPort, PList listToAppend); + +/** + * @brief Removes a port from a VLAN entity and retrieves trunk ports that need cleanup. + * + * This function removes a platform port from its entity and dereferences all trunk ports + * that were dependent on paths involving this entity. Trunk ports with no remaining path dependencies + * are added to the output list for removal/cleanup. + * + * @param[in,out] vidState - Pointer to the VLAN trunk state structure. + * @param[in] oldPort - Pointer to the platform port to be removed. + * @param[out] listToAppend - Pointer to list where trunk ports requiring cleanup will be appended. + * + * @return The number of trunk ports that were changed/removed. + */ int removeAndGetTrunkPorts(PVlanTrunkState vidState, PPlatformPort oldPort, PList listToAppend); +/** + * @brief Retrieves or creates the VLAN state structure for a specified VLAN ID. + * + * This function searches for an existing VLAN state matching the given VLAN ID. + * If found, it returns the existing state. If not found, it allocates a new VLAN state structure, + * loads its configuration from persistent storage, and returns it. + * + * @param[out] vidState - Pointer to receive the VLAN trunk state structure pointer. + * @param[in] vid - VLAN ID to search for or create. + * + * @return Status indicating if state was found or created. + * @retval 1 if an existing VLAN state was found. + * @retval 0 if a new VLAN state was allocated and loaded. + */ int getVlanState(PVlanTrunkState* vidState, int vid); //---- Private - -/** Search for entity within the specified vid. - * Returns: NULL if entity is not a vid member. EntityPortList otherwise. +/** + * @brief Searches for an entity within the specified VLAN state. + * + * This function iterates through the member entities list of the VLAN state to find + * a matching entity by entity ID. + * + * @param[in] vidState - Pointer to the VLAN trunk state structure to search. + * @param[in] entity - Entity ID to search for. + * + * @return Pointer to the EntityPortList structure if found. + * @retval Non-NULL pointer if entity is a VLAN member. + * @retval NULL if entity is not a VLAN member. */ PEntityPortList getEntity(PVlanTrunkState vidState, int entity); +/** + * @brief Adds a new entity to the VLAN state. + * + * This function allocates and initializes a new entity port list structure and adds it to the + * member entities list of the VLAN state. The entities dirty flag is set to indicate changes. + * + * @param[in,out] vidState - Pointer to the VLAN trunk state structure. + * @param[in] entity - Entity ID to add. + * + * @return Pointer to the newly created EntityPortList structure. + */ PEntityPortList addEntity(PVlanTrunkState vidState, int entity); +/** + * @brief Adds a new trunk port to the VLAN state. + * + * This function allocates and initializes a new trunk port structure with the specified platform port + * and adds it to the trunk ports list of the VLAN state. The trunks dirty flag is set to indicate changes. + * + * @param[in,out] vidState - Pointer to the VLAN trunk state structure. + * @param[in] platport - Pointer to the platform port to be added as a trunk. + * + * @return Pointer to the newly created TrunkPort structure. + */ PTrunkPort addTrunkPort(PVlanTrunkState vidState, PPlatformPort platport); +/** + * @brief Adds an entity path dependency to a trunk port. + * + * This function allocates and adds a new entity path to the trunk port's path list, + * indicating a dependency relationship. The trunk port's dirty flag is set to indicate changes. + * + * @param[in,out] port - Pointer to the trunk port structure. + * @param[in] path - Pointer to the entity path structure to be added. + * + * @return Status of the operation. + * @retval 0 on success. + */ int addPathToTrunkPort(PTrunkPort port, PEntityPath path); -/** Adds a path reference to this port, or adds the port - * if it was not previously referenced. - * Returns: 1 if new port is added to the vid. 0 if only a ref is added +/** + * @brief Adds a path reference to a trunk port, or adds the port if not previously referenced. + * + * This function searches for an existing trunk port matching the specified platform port. + * If found, it adds the path dependency to the existing port. If not found, it creates a new + * trunk port and adds it to the VLAN state with the specified path dependency. + * + * @param[in,out] vidState - Pointer to the VLAN trunk state structure. + * @param[in] port - Pointer to the platform port to reference. + * @param[in] path - Pointer to the entity path dependency to add. + * + * @return Status indicating if a new port was added. + * @retval 1 if a new port was added to the VLAN. + * @retval 0 if only a path reference was added to an existing port. */ int refTrunkPort(PVlanTrunkState vidState, PPlatformPort port, PEntityPath path); -/** Searches for and removes path references matching the specified entity. - * Returns: 1 if no paths remain for this trunk port. 0 otherwise. +/** + * @brief Searches for and removes path references matching the specified entity. + * + * This function iterates through the trunk port's path list and removes all paths + * where either endpoint (A or B) matches the specified entity ID. The port's dirty flag + * is set if any paths are removed. + * + * @param[in,out] port - Pointer to the trunk port structure. + * @param[in] entity - Entity ID to match and remove from path dependencies. + * + * @return Status indicating if all paths were removed. + * @retval 1 if no paths remain for this trunk port. + * @retval 0 if paths still exist for this trunk port. */ int deRefTrunkPort(PTrunkPort port, int entity); -/**Remove member port, and if the port list is empty, remove this entity from the vid. - * Returns: 1 if entity was emptied. 0 otherwise. +/** + * @brief Removes a member port from an entity, and removes the entity if it becomes empty. + * + * This function searches for the specified entity in the VLAN state, removes the given port + * from its member port list, and if the entity has no remaining member ports, removes the entity + * from the VLAN state and clears its persistent storage configuration. + * + * @param[in,out] vidState - Pointer to the VLAN trunk state structure. + * @param[in] entity - Entity ID from which to remove the port. + * @param[in] port - Pointer to the platform port to remove. + * + * @return Status indicating if the entity was emptied. + * @retval 1 if the entity was emptied and removed. + * @retval 0 if the entity still has remaining member ports. */ int deRefEntity(PVlanTrunkState vidState, int entity, PPlatformPort port); +/** + * @brief Adds a member port to an entity's port list. + * + * This function adds a platform port to the entity's member port list if it is not already present. + * It checks for duplicate ports by comparing HAL IDs and using the HAL's equality check. + * The entity's dirty flag is set to indicate changes. + * + * @param[in,out] entity - Pointer to the entity port list structure. + * @param[in] port - Pointer to the platform port to add. + * + * @return Status of the operation. + * @retval 0 if the port was added successfully or already exists. + * @retval -1 if the port pointer is NULL. + */ int addMemberPort(PEntityPortList entity, PPlatformPort port); + +/** + * @brief Removes a member port from an entity's port list. + * + * This function searches for a platform port in the entity's member port list by comparing + * HAL IDs and using the HAL's equality check. If found, it removes the port and sets + * the entity's dirty flag. + * + * @param[in,out] entity - Pointer to the entity port list structure. + * @param[in] port - Pointer to the platform port to remove. + * + * @return Status of the operation. + * @retval 1 if the port was found and removed. + * @retval 0 if the port was not found in the list. + */ int remMemberPort(PEntityPortList entity, PPlatformPort port); +/** + * @brief Saves the VLAN state to persistent storage. + * + * This function persists the current VLAN state including member entities, their port memberships, + * trunk ports, and path dependencies to endpoint storage. It processes dirty flags to determine + * which elements need to be saved. + * + * @param[in] vidState - Pointer to the VLAN trunk state structure to save. + * + * @return Status of the operation. + * @retval 0 on success. + */ int saveVlanState(PVlanTrunkState vidState); + +/** + * @brief Loads the VLAN state from persistent storage. + * + * This function retrieves VLAN configuration from endpoint storage including entity memberships, + * member ports for each entity, trunk ports, and their path dependencies. It populates the VLAN + * state structure and clears all dirty flags after loading. + * + * @param[in,out] vidState - Pointer to the VLAN trunk state structure to populate. + * + * @return Status of the operation. + * @retval 0 on success. + */ int loadVlanState(PVlanTrunkState vidState); #endif diff --git a/source/include/service_multinet/service_multinet_swfab_ep.h b/source/include/service_multinet/service_multinet_swfab_ep.h index 86900999..d9f03107 100644 --- a/source/include/service_multinet/service_multinet_swfab_ep.h +++ b/source/include/service_multinet/service_multinet_swfab_ep.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2015] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -42,18 +42,136 @@ #define SWFAB_VID_ENTITYMEMBER_KEY_FORMAT(vlan) "vid_%d_entities", vlan #define SWFAB_VID_TRUNKMEMBER_KEY_FORMAT(vlan) "vid_%d_trunkports", vlan +/** + * @brief Sets the member port names for a specific entity within a VLAN. + * + * This function stores the list of member port names associated with an entity in the specified VLAN + * to persistent storage using sysevent. The key format is "vid__entity__members". + * + * @param[in] vid - VLAN ID. + * @param[in] entity - Entity ID. + * @param[in] memberPortNames - Array of port name strings to set as members. + * @param[in] numPorts - Number of ports in the memberPortNames array. + * + * @return Status of the operation. + * @retval 0 on success. + */ int ep_set_entity_vid_portMembers(int vid, int entity, char* memberPortNames[], int numPorts); + +/** + * @brief Sets the list of entity IDs that are members of a VLAN. + * + * This function stores the list of entity IDs associated with a VLAN to persistent storage + * using sysevent. The key format is "vid__entities". + * + * @param[in] vid - VLAN ID. + * @param[in] entities - Array of entity IDs to set as VLAN members. + * @param[in] numEntities - Number of entities in the entities array. + * + * @return Status of the operation. + * @retval 0 on success. + */ int ep_set_entity_vidMembers(int vid, int entities[], int numEntities); +/** + * @brief Sets the entity path dependencies for a trunk port in a VLAN. + * + * This function stores the list of entity path dependencies (A,B pairs) for a trunk port + * in the specified VLAN to persistent storage using sysevent. The key format is + * "vid__port__paths". Each path is stored as "A,B" format. + * + * @param[in] vid - VLAN ID. + * @param[in] portName - Name of the trunk port. + * @param[in] paths - Array of EntityPath structures containing A and B entity endpoints. + * @param[in] numPaths - Number of paths in the paths array. + * + * @return Status of the operation. + * @retval 0 on success. + */ int ep_set_trunkPort_vid_paths(int vid, char* portName, PEntityPath paths, int numPaths); -int ep_set_trunkPort_vidMembers(int vid, char* portNames[], int numPorts); - +/** + * @brief Sets the list of trunk port names for a VLAN. + * + * This function stores the list of trunk port names associated with a VLAN to persistent storage + * using sysevent. The key format is "vid__trunkports". + * + * @param[in] vid - VLAN ID. + * @param[in] portNames - Array of trunk port name strings. + * @param[in] numPorts - Number of ports in the portNames array. + * + * @return Status of the operation. + * @retval 0 on success. + */ +int ep_set_trunkPort_vidMembers(int vid, char* portNames[], int numPorts); +/** + * @brief Retrieves the member port names for a specific entity within a VLAN. + * + * This function retrieves the list of member port names associated with an entity in the specified VLAN + * from persistent storage using sysevent. Port names are tokenized from space-separated storage format. + * The function respects MAX_ADD_PORTS limit. + * + * @param[in] vid - VLAN ID. + * @param[in] entity - Entity ID. + * @param[out] memberPortNames - Array of pointers to receive port name strings from buf. + * @param[in,out] numPorts - Pointer to number of ports retrieved. + * @param[out] buf - Buffer to store port name strings. + * @param[in] bufSize - Size of the buf buffer in bytes. + * + * @return Status of the operation. + * @retval 0 on success. + */ int ep_get_entity_vid_portMembers(int vid, int entity, char* memberPortNames[], int* numPorts, char buf[], int bufSize ); + +/** + * @brief Retrieves the list of entity IDs that are members of a VLAN. + * + * This function retrieves the list of entity IDs associated with a VLAN from persistent storage + * using sysevent. Entity IDs are tokenized from space-separated storage format. + * + * @param[in] vid - VLAN ID. + * @param[out] entities - Array to receive entity IDs. + * @param[in,out] numEntities - Pointer to number of entities retrieved. + * + * @return Status of the operation. + * @retval 0 on success. + */ int ep_get_entity_vidMembers(int vid, int entities[], int* numEntities); +/** + * @brief Retrieves the entity path dependencies for a trunk port in a VLAN. + * + * This function retrieves the list of entity path dependencies (A,B pairs) for a trunk port + * in the specified VLAN from persistent storage using sysevent. Each path is parsed from + * "A,B" comma-separated format. + * + * @param[in] vid - VLAN ID. + * @param[in] portName - Name of the trunk port. + * @param[out] paths - Array of EntityPath structures to receive path dependencies. + * @param[in,out] numPaths - Pointer to number of paths retrieved. + * + * @return Status of the operation. + * @retval 0 on success. + */ int ep_get_trunkPort_vid_paths(int vid, char* portName, PEntityPath paths, int* numPaths); + +/** + * @brief Retrieves the list of trunk port names for a VLAN. + * + * This function retrieves the list of trunk port names associated with a VLAN from persistent storage + * using sysevent. Port names are tokenized from space-separated storage format. + * The function respects MAX_ADD_PORTS limit. + * + * @param[in] vid - VLAN ID. + * @param[out] portNames - Array of pointers to receive port name strings from buf. + * @param[in,out] numPorts - Pointer to number of ports retrieved. + * @param[out] buf - Buffer to store port name strings. + * @param[in] bufSize - Size of the buf buffer in bytes. + * + * @return Status of the operation. + * @retval 0 on success. + */ int ep_get_trunkPort_vidMembers(int vid, char* portNames[], int* numPorts, char buf[], int bufSize); #endif diff --git a/source/include/service_multinet/service_multinet_swfab_gre.h b/source/include/service_multinet/service_multinet_swfab_gre.h index 5217e0cc..e5e7b6c2 100644 --- a/source/include/service_multinet/service_multinet_swfab_gre.h +++ b/source/include/service_multinet/service_multinet_swfab_gre.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2015] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -37,6 +37,22 @@ #include "service_multinet_swfab.h" +/** + * @brief Initializes a GRE (Generic Routing Encapsulation) interface for a network instance. + * + * This function creates and configures a GRE interface by invoking the handle_gre.sh script + * with the network instance ID and port ID. Platform-specific implementations handle standard + * GRE interfaces (like gretap0) and Intel GRE hotspot configurations differently. + * + * @param[in] args - Array of SWFabHALArg structures containing port ID and network hints.\n + * args[0].portID contains the GRE interface name.\n + * args[0].hints.network->inst contains the network instance ID. + * @param[in] numArgs - Number of arguments in the args array. + * @param[in] up - Boolean flag indicating whether to bring the interface up (TRUE) or down (FALSE). + * + * @return Status of the operation. + * @retval 0 on success. + */ int greIfInit(PSWFabHALArg args, int numArgs, BOOL up) ; -#endif +#endif diff --git a/source/include/service_multinet/service_multinet_swfab_plat.h b/source/include/service_multinet/service_multinet_swfab_plat.h index 2a13dd6e..21eda0a0 100644 --- a/source/include/service_multinet/service_multinet_swfab_plat.h +++ b/source/include/service_multinet/service_multinet_swfab_plat.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2015] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -38,29 +38,52 @@ #include "service_multinet_base.h" #include "service_multinet_swfab_deps.h" -/**The purpose of this function is to fill in the "map" member of iface - * with a PPlatformPort pointer to a complete platform port, including - * HAL references. It will be assumed that the pointers returned from this - * function are internally managed by the mapping code, and will not be freed - * by the framework. +/** + * @brief Maps a network interface to its corresponding platform port. + * + * This is a platform-specific mapping between DM (Data Model) ports and physical ports. + * The function fills in the "map" member of the interface structure with a PPlatformPort pointer + * to a complete platform port, including HAL references. Integrators may utilize any approach + * to expedite mapping, such as port naming conventions. The pointers returned from this function + * are internally managed by the mapping code and will not be freed by the framework. + * + * @param[in,out] iface - Pointer to network interface structure. + * \n iface->type->name contains the interface type (WiFi, SW, Gre, Eth, Moca, virt). + * \n iface->name contains the interface name for parsing. + * \n iface->map will be populated with the platform port mapping. + * + * @return Status of the operation. + * @retval 0 on success. */ int mapToPlat(PNetInterface iface); - /** - * Return a pointer to a EntityPathDeps structure that defines a list of trunk ports - * requiring configuration to connect the two specified entities. It is expected that - * this information can be provided for any combination of entity IDs. entityLow will - * be less than entityHigh. - * - * This mapping must remain static. The framework does not support re-mapping of trunk - * ports for existing paths. + * @brief Returns entity path dependency information for connecting two entities. + * + * This function returns a pointer to an EntityPathDeps structure that defines a list of trunk ports + * requiring configuration to connect the two specified entities. It is expected that this information + * can be provided for any combination of entity IDs. This mapping must remain static - the framework + * does not support re-mapping of trunk ports for existing paths. + * + * @param[in] entityLow - Lower entity ID. Must be less than entityHigh. + * @param[in] entityHigh - Higher entity ID. Must be greater than entityLow. + * + * @return Pointer to EntityPathDeps structure containing trunk port configuration requirements. */ PEntityPathDeps getPathDeps(int entityLow, int entityHigh); /** - * Return the platform port represented by its string ID, retrieved via its HAL's stringID - * function. Primarily used when loading from nonvol or string based runtime data store. + * @brief Returns the platform port represented by its string ID. + * + * This function maps a string-based port identifier to its corresponding platform port structure. + * The string ID is retrieved via the HAL's stringID function. This is primarily used when loading + * from non-volatile storage or string-based runtime data stores. + * + * @param[in] portIdString - String identifier of the port to map. + * + * @return Pointer to the platform port structure. + * @retval Non-NULL pointer if mapping is found. + * @retval NULL if no mapping is found for the given string. */ PPlatformPort plat_mapFromString(char* portIdString); diff --git a/source/include/service_multinet/service_multinet_util.h b/source/include/service_multinet/service_multinet_util.h index 29827e27..ed684b30 100644 --- a/source/include/service_multinet/service_multinet_util.h +++ b/source/include/service_multinet/service_multinet_util.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2015] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -38,14 +38,14 @@ typedef struct listItem { struct listItem* prev; struct listItem* next; - + void* data; } ListItem, *PListItem; typedef struct list { PListItem first; PListItem last; - + int count; } List, *PList; @@ -55,17 +55,111 @@ typedef struct listIterator { int bGiven; } ListIterator, *PListIterator; +/** +* @brief Add an item to a linked list. +* +* @param[in,out] list - Pointer to the List structure. +* @param[in] itemData - Pointer to the data to add to the list. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int addToList(PList list, void* itemData); + +/** +* @brief Add an item to a linked list with memory allocation. +* +* @param[in,out] list - Pointer to the List structure. +* @param[in] dataSize - Size in bytes of the data to allocate and add. +* +* @return Pointer to the allocated data. +* @retval pointer to allocated data on success +* @retval NULL on failure. +* +*/ void* addAndAlloc(PList list, int dataSize); + +/** +* @brief Remove an item from a linked list. +* +* @param[in,out] list - Pointer to the List structure. +* @param[in] item - Pointer to the ListItem to remove. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int removeFromList(PList list, PListItem item); + +/** +* @brief Clear all items from a linked list. +* +* @param[in,out] list - Pointer to the List structure to clear. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int clearList(PList list); + +/** +* @brief Get the number of items in a linked list. +* +* @param[in] list - Pointer to the List structure. +* +* @return The number of items in the list. +* +*/ int listSize(PList list); +/** +* @brief Initialize an iterator for a linked list. +* +* @param[in] list - Pointer to the List structure to iterate. +* @param[out] iterator - Pointer to the ListIterator structure to initialize. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int initIterator(PList list, PListIterator iterator); + //int copyIterator(PListIterator to, PListIterator from); + +/** +* @brief Get the next item from a list iterator. +* +* @param[in,out] iterator - Pointer to the ListIterator structure. +* +* @return Pointer to the next ListItem +* @retval pointer to next item on success. +* @retval NULL if no more items. +* +*/ PListItem getNext(PListIterator iterator); + +/** +* @brief Get the current item from a list iterator. +* +* @param[in] iterator - Pointer to the ListIterator structure. +* +* @return Pointer to the current ListItem +* @retval pointer to current item on success. +* @retval NULL if no current item. +* +*/ PListItem getCurrent(PListIterator iterator); -int removeCurrent(PListIterator iterator); +/** +* @brief Remove the current item from a list iterator. +* +* @param[in,out] iterator - Pointer to the ListIterator structure. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ +int removeCurrent(PListIterator iterator); #endif diff --git a/source/include/syscfg/syscfg.h b/source/include/syscfg/syscfg.h index a93d5542..08d9b68c 100644 --- a/source/include/syscfg/syscfg.h +++ b/source/include/syscfg/syscfg.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -62,17 +62,21 @@ extern "C"{ #endif -/* - * Procedure : syscfg_create - * Purpose : Create syscfg shared memory and load entries from persistent storage - * Parameters : - * file - filesystem 'file' where syscfg is stored - * Return Values : - * 0 - success - * ERR_INVALID_PARAM - invalid arguments - * ERR_IO_FAILURE - syscfg file unavailable - * Notes : - */ +/** +* @brief Create syscfg shared memory and load entries from persistent storage. +* +* This function initialization SYSCFG from persistent storage. +* +* @param[in] file - Pointer to the filesystem file path string where syscfg is stored. +* @param[in] max_file_sz - Maximum file size in bytes for the syscfg persistent storage. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval ERR_INVALID_PARAM if invalid arguments are provided. +* @retval ERR_IO_FAILURE if syscfg file is unavailable. +* @retval ERR_SHM_CREATE if error creating shared memory. +* +*/ int syscfg_create(const char *file, long int max_file_sz); /* @@ -87,80 +91,196 @@ static inline int syscfg_init (void) return 0; } -/* - * Procedure : syscfg_destroy - * Purpose : Destroy syscfg shared memory context - * Parameters : - * None - * Return Values : - * 0 - success - * ERR_INVALID_PARAM - invalid arguments - * ERR_IO_FAILURE - syscfg file unavailable - * Notes : - * syscfg destroy should happen only during system shutdown. - * *NEVER* call this API in any other scenario!! - */ +/** +* @brief Destroy syscfg shared memory context. +* +* syscfg destroy should happen only during system shutdown, should never call +* this API in any other scenario. +* +* @return None. +* +*/ void syscfg_destroy(); -/* - * Procedure : syscfg_get - * Purpose : Retrieve an entry from syscfg - * Parameters : - * ns - namespace string (optional) - * name - name string, entry to add - * out_val - buffer to store output value string - * outbufsz - output buffer size - * Return Values : - * 0 on success, -1 on error - */ +/** +* @brief Retrieve an entry from syscfg. +* +* @param[in] ns - Pointer to the namespace string (optional, can be NULL). +* @param[in] name - Pointer to the name string of the entry to retrieve. +* @param[out] out_value - Pointer to the buffer to store the output value string. +* @param[in] outbufsz - Size of the output buffer in bytes. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval -1 on error. +* +*/ int syscfg_get(const char *ns, const char *name, char *out_value, int outbufsz); -/* - * Procedure : syscfg_getall - * Purpose : Retrieve all entries from syscfg - * Parameters : - * buf - output buffer to store syscfg entries - * bufsz - size of output buffer - * outsz - number of bytes return into given buffer - * Return Values : - * 0 - on success - * ERR_xxx - various errors codes dependening on the failure - * Notes : - * useful for clients to dump the whole syscfg data - */ +/** +* @brief Retrieve all entries from syscfg. +* +* This function retrieves all entries from syscfg. +* +* @param[out] buf - Pointer to the output buffer to store syscfg entries. +* @param[in] bufsz - Size of the output buffer in bytes. +* @param[out] outsz - Pointer to store the number of bytes returned into the given buffer. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval ERR_xxx various error codes depending on the failure. +* +* @note Useful for clients to dump the whole syscfg data. +*/ int syscfg_getall(char *buf, int bufsz, int *outsz); -/* - * Like syscfg_getall(), but returns pairs of entries separated by - * newlines instead nul characters. - */ +/** +* @brief Retrieve all entries from syscfg with newline-separated pairs. +* +* @param[out] buf - Pointer to the output buffer to store syscfg entries. +* @param[in] bufsz - Size of the output buffer in bytes. +* @param[out] outsz - Pointer to store the number of bytes returned into the given buffer. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval ERR_xxx various error codes depending on the failure. +* +*/ int syscfg_getall2(char *buf, size_t bufsz, size_t *outsz); -/* - * Procedure : syscfg_set - * Purpose : Adds an entry to syscfg - * Parameters : - * ns - namespace string (optional) - * name - name string, entry to add - * value - value string to associate with name - * Return Values : - * 0 - success - * ERR_xxx - various errors codes dependening on the failure - * Notes : - * Only changes syscfg hash table, persistent store contents - * not changed until 'commit' operation - */ - +/** +* @brief Add an entry to syscfg with namespace. +* +* This function adds an entry to syscfg with namespace. +* +* @param[in] ns - Pointer to the namespace string. +* @param[in] name - Pointer to the name string of the entry to add. +* @param[in] value - Pointer to the value string to associate with the name. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval ERR_xxx various error codes depending on the failure. +* +* @note Only changes syscfg hash table, persistent store contents not changed until 'commit' operation. +*/ int syscfg_set_ns (const char *ns, const char *name, const char *value); + +/** +* @brief Add an entry to syscfg with namespace and commit to persistent storage. +* +* @param[in] ns - Pointer to the namespace string. +* @param[in] name - Pointer to the name string of the entry to add. +* @param[in] value - Pointer to the value string to associate with the name. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval ERR_xxx various error codes depending on the failure. +* +* * @note Only changes syscfg hash table, persistent store contents not changed until 'commit' operation. +*/ int syscfg_set_ns_commit (const char *ns, const char *name, const char *value); + +/** +* @brief Add an entry with unsigned long value to syscfg with namespace. +* +* @param[in] ns - Pointer to the namespace string. +* @param[in] name - Pointer to the name string of the entry to add. +* @param[in] value - Unsigned long value to associate with the name. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval ERR_xxx various error codes depending on the failure. +* +* @note Only changes syscfg hash table, persistent store contents not changed until 'commit' operation. +*/ int syscfg_set_ns_u (const char *ns, const char *name, unsigned long value); + +/** +* @brief Add an entry with unsigned long value to syscfg with namespace and commit. +* +* @param[in] ns - Pointer to the namespace string. +* @param[in] name - Pointer to the name string of the entry to add. +* @param[in] value - Unsigned long value to associate with the name. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval ERR_xxx various error codes depending on the failure. +* +* @note Only changes syscfg hash table, persistent store contents not changed until 'commit' operation. +*/ int syscfg_set_ns_u_commit (const char *ns, const char *name, unsigned long value); +/** +* @brief Add an entry to syscfg without namespace. +* +* @param[in] name - Pointer to the name string of the entry to add. +* @param[in] value - Pointer to the value string to associate with the name. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval ERR_xxx various error codes depending on the failure. +* +* @note Only changes syscfg hash table, persistent store contents not changed until 'commit' operation. +*/ int syscfg_set_nns (const char *name, const char *value); + +/** +* @brief Add an entry to syscfg without namespace and commit to persistent storage. +* +* @param[in] name - Pointer to the name string of the entry to add. +* @param[in] value - Pointer to the value string to associate with the name. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval ERR_xxx various error codes depending on the failure. +* +* @note Only changes syscfg hash table, persistent store contents not changed until 'commit' operation. +*/ int syscfg_set_nns_commit (const char *name, const char *value); + +/** +* @brief Add an entry with unsigned long value to syscfg without namespace. +* +* @param[in] name - Pointer to the name string of the entry to add. +* @param[in] value - Unsigned long value to associate with the name. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval ERR_xxx various error codes depending on the failure. +* +* @note Only changes syscfg hash table, persistent store contents not changed until 'commit' operation. +*/ int syscfg_set_nns_u (const char *name, unsigned long value); + +/** +* @brief Add an entry with unsigned long value to syscfg without namespace and commit. +* +* @param[in] name - Pointer to the name string of the entry to add. +* @param[in] value - Unsigned long value to associate with the name. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval ERR_xxx various error codes depending on the failure. +* +* @note Only changes syscfg hash table, persistent store contents not changed until 'commit' operation. +*/ int syscfg_set_nns_u_commit (const char *name, unsigned long value); +/** +* @brief Add an entry to syscfg with optional namespace. +* +* This is a convenience wrapper function that automatically selects between namespace and +* non-namespace variants based on whether the ns parameter is NULL. +* +* @param[in] ns - Pointer to the namespace string. +* @param[in] name - Pointer to the name string of the entry to add. +* @param[in] value - Pointer to the value string to associate with the name. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval ERR_xxx various error codes depending on the failure. +* +*/ static inline int syscfg_set (const char *ns, const char *name, const char *value) { if (ns) @@ -169,6 +289,21 @@ static inline int syscfg_set (const char *ns, const char *name, const char *valu return syscfg_set_nns (name, value); } +/** +* @brief Add an entry to syscfg with optional namespace and commit to persistent storage. +* +* This is a convenience wrapper function that automatically selects between namespace and +* non-namespace variants based on whether the ns parameter is NULL. +* +* @param[in] ns - Pointer to the namespace string. +* @param[in] name - Pointer to the name string of the entry to add. +* @param[in] value - Pointer to the value string to associate with the name. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval ERR_xxx various error codes depending on the failure. +* +*/ static inline int syscfg_set_commit (const char *ns, const char *name, const char *value) { if (ns) @@ -177,6 +312,21 @@ static inline int syscfg_set_commit (const char *ns, const char *name, const cha return syscfg_set_nns_commit (name, value); } +/** +* @brief Add an entry with unsigned long value to syscfg with optional namespace. +* +* This is a convenience wrapper function that automatically selects between namespace and +* non-namespace variants based on whether the ns parameter is NULL. +* +* @param[in] ns - Pointer to the namespace string. +* @param[in] name - Pointer to the name string of the entry to add. +* @param[in] value - Unsigned long value to associate with the name. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval ERR_xxx various error codes depending on the failure. +* +*/ static inline int syscfg_set_u (const char *ns, const char *name, unsigned long value) { if (ns) @@ -185,6 +335,21 @@ static inline int syscfg_set_u (const char *ns, const char *name, unsigned long return syscfg_set_nns_u (name, value); } +/** +* @brief Add an entry with unsigned long value to syscfg with optional namespace and commit. +* +* This is a convenience wrapper function that automatically selects between namespace and +* non-namespace variants based on whether the ns parameter is NULL. +* +* @param[in] ns - Pointer to the namespace string. +* @param[in] name - Pointer to the name string of the entry to add. +* @param[in] value - Unsigned long value to associate with the name. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval ERR_xxx various error codes depending on the failure. +* +*/ static inline int syscfg_set_u_commit (const char *ns, const char *name, unsigned long value) { if (ns) @@ -193,52 +358,50 @@ static inline int syscfg_set_u_commit (const char *ns, const char *name, unsigne return syscfg_set_nns_u_commit (name, value); } -/* - * Procedure : syscfg_unset - * Purpose : Remove an entry from syscfg - * Parameters : - * ns - namespace string (optional) - * name - name string, entry to remove - * Return Values : - * 0 - success - * ERR_xxx - various errors codes dependening on the failure - * Notes : - * Only changes syscfg hash table, persistent store contents - * not changed until 'commit' operation - */ +/** +* @brief Remove an entry from syscfg. +* +* @param[in] ns - Pointer to the namespace string. +* @param[in] name - Pointer to the name string of the entry to remove. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval ERR_xxx various error codes depending on the failure. +* +* @note Only changes syscfg hash table, persistent store contents not changed until 'commit' operation. +*/ int syscfg_unset(const char *ns, const char *name); -/* - * Procedure : syscfg_commit - * Purpose : commits current stats of syscfg hash table data - * to persistent store - * Parameters : - * None - * Return Values : - * 0 - success - * ERR_IO_xxx - various IO errors dependening on the failure - * Notes : - * WARNING: will overwrite persistent store - * Persistent store location specified during syscfg_create() is cached - * in syscfg shared memory and used as the target for commit - */ +/** +* @brief Commit current state of syscfg hash table data to persistent store. +* +* This function commits current stats of syscfg hash table to persistent storage. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval ERR_IO_xxx various IO error codes depending on the failure. +* +* @note This operation will overwrite the existing persistent storage. +* The persistent store location set during syscfg_create() is cached in syscfg +* shared memory and used as the commit target. +*/ int syscfg_commit(); -/* - * Procedure : syscfg_getsz - * Purpose : Get current & maximum peristent storage size - * of syscfg content - * Parameters : - * used_sz - return buffer of used size - * max_sz - return buffer of max size - * Return Values : - * 0 - success - * ERR_xxx - various errors codes dependening on the failure - */ +/** +* @brief Get current and maximum persistent storage size of syscfg content. +* +* @param[out] used_sz - Pointer to store the used size in bytes. +* @param[out] max_sz - Pointer to store the maximum size in bytes. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval ERR_xxx various error codes depending on the failure. +* +*/ int syscfg_getsz (long int *used_sz, long int *max_sz); #ifdef __cplusplus } #endif -#endif /* _SYSCFG_H_ */ +#endif /* _SYSCFG_H_ */ \ No newline at end of file diff --git a/source/include/sysevent/sysevent.h b/source/include/sysevent/sysevent.h index 4a27f70f..f744d4e3 100644 --- a/source/include/sysevent/sysevent.h +++ b/source/include/sysevent/sysevent.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -49,7 +49,7 @@ extern "C" { #define SE_SERVER_WELL_KNOWN_PORT 52367 /* - * Well known UDS + * Well known UDS */ #define UDS_PATH "/tmp/syseventd_connection" @@ -235,17 +235,19 @@ typedef struct { */ #define SE_MSG_STRING_OVERHEAD (sizeof(unsigned int)) -/* - * Procedure : SE_msg_get_string - * Purpose : Get a string from a SE_msg buffer. The buffer - * must be pointing at the se_msg_string containing the string - * Parameters : - * msg : A pointer to the start of the se_msg_string - * size : On return the number of bytes that the se_msg_string occupied - * Return Code : - * NULL : problem, string not gotten - * !NULL : string - */ +/** +* @brief Get a string from a sysevent message buffer. +* +* This function retrieves a string from a SE_msg buffer. The buffer must be pointing +* at the se_msg_string containing the string. +* +* @param[in] msg - Pointer to the start of the se_msg_string. +* @param[out] size - Pointer to store the number of bytes that the se_msg_string occupied. +* +* @return Pointer to the string. +* @retval Non-NULL pointer to the string on success. +* @retval NULL if there is a problem and string cannot be retrieved. +*/ char *SE_msg_get_string(char *msg, int *size); /* @@ -869,469 +871,504 @@ typedef struct =============================================================== */ -/* - * Procedure : SE_strerror - * Purpose : Return a string version of an error code - * Parameters : - * error : The error - * Return Code : - * The string. - * Do NOT save this string. It has no lifespan - */ +/** +* @brief Returns a string description of a sysevent error code. +* +* This function converts a numeric error code returned by other sysevent APIs into a +* human-readable string. +* +* @param[in] error - The error code. +* +* @return Pointer to a static string describing the error. +* +* @note Do NOT save this string. It has no lifespan. +*/ char *SE_strerror (int error); -/* - * Procedure : SE_print_mtype - * Purpose : Return a string for a msgtype - * Parameters : - * mtype : The msg type - * Return Code : - * The string. - * Do NOT save this string. It has no lifespan - */ +/** +* @brief Return a string representation for a message type. +* +* @param[in] mtype - The message type. +* +* @return Pointer to the message type string. +* +* @note Do NOT save this string. It has no lifespan. +*/ char *SE_print_mtype (int mtype); -/* - * Procedure : init_libsysevent - * Purpose : initialize this library - * Parameters : - * name : name of the user of this library - * Return Code : - * Notes : This doesn't need to be called by most users - * of libsysevent since it is implicitly called during - * sysevent_open. It is used by syseventd. - */ +/** +* @brief Initialize the libsysevent library. +* +* @param[in] name - Name of the user of this library. +* +* @return None. +* +* @note This doesn't need to be called by most users of libsysevent +* since it is implicitly called during sysevent_open. It is used by syseventd +*/ void init_libsysevent(const char* const name); -/* - * Procedure : sysevent_open - * Purpose : Connect to the sysevent daemon - * Parameters : - * ip : ip address to connect to. - * This may be dots and dashes or hostname - * port : port to connect to - * version : version of client - * id : name of client - * token : on return, an opaque value to be used in future calls for this session - * Return Code : - * NULL : error - * >0 : file descriptor for connection - */ +/** +* @brief Connect to the sysevent daemon. +* +* @param[in] ip - IP address to connect to. +* @param[in] port - Port to connect to. +* @param[in] version - Version of client. +* @param[in] id - Name of client. +* @param[out] token - Pointer to receive an opaque value. +* +* @return File descriptor for the connection. +* @retval >0 file descriptor if connection is successful. +* @retval -1 on error. +*/ int sysevent_open(char *ip, unsigned short port, int version, char *id, token_t *token); -int sysevent_open_data (char *ip, unsigned short port, int version, char *id, token_t *token); +/** +* @brief Connect to the sysevent daemon for binary data operations. +* +* @param[in] ip - IP address of the sysevent daemon. +* @param[in] port - Port number of the sysevent daemon. +* @param[in] version - Version of client. +* @param[in] id - Human-readable client identifier. +* @param[out] token - Pointer to receive an opaque value. +* +* @return File descriptor for the connection. +* @retval >0 file descriptor if connection is successful. +* @retval -1 on error. +*/ +int sysevent_open_data (char *ip, unsigned short port, int version, char *id, token_t *token); -/* - * Procedure : sysevent_local_open - * Purpose : Connect to the sysevent daemon using Unix Domain Socket - * Parameters : - * target : the name of the uds to connect to - * version : version of client - * id : name of client - * token : opaque id for future contact - * Return Code : - * The file descriptor to use in future calls - * -1 if error - */ +/** +* @brief Connect to the sysevent daemon using Unix Domain Socket. +* +* @param[in] target - The name of the UDS to connect to. +* @param[in] version - Version of client. +* @param[in] id - Name of client. +* @param[out] token - Pointer to receive opaque id. +* +* @return The file descriptor. +* @retval >=0 file descriptor on success. +* @retval -1 on error. +*/ int sysevent_local_open (char *target, int version, char *id, token_t *token); + +/** +* @brief Connect to the sysevent daemon using Unix Domain Socket for binary data operations. +* +* @param[in] target - The name of the UDS to connect to. +* @param[in] version - Version of client. +* @param[in] id - Name of client. +* @param[out] token - Pointer to receive opaque id. +* +* @return The file descriptor. +* @retval >=0 file descriptor on success. +* @retval -1 on error. +*/ int sysevent_local_open_data (char *target, int version, char *id, token_t *token); -/* - * Procedure : sysevent_close - * Purpose : Disconnect from the sysevent daemon - * Parameters : - * fd : the file descriptor to close - * token : The server provided opaque id of the client - * Return Code : - * 0 : disconnected - * !0 : some error - */ +/** +* @brief Disconnect from the sysevent daemon. +* +* This function close a connection to the sysevent daemon. +* +* @param[in] fd - The file descriptor to close. +* @param[in] token - The server provided opaque id of the client. +* +* @return Status of the operation. +* @retval 0 if disconnected successfully. +* @retval Non-zero on error. +*/ int sysevent_close(const int fd, const token_t token); -/* - * Procedure : sysevent_ping - * Purpose : Ping a connection to the sysevent daemon - * Parameters : - * fd : the file descriptor to ping - * token : Server provided opaque value - * Return Code : - * 0 : ping msg sent - * !0 : some error - * Note : We only told sysevent daemon to ping reply. We are not handling the - * reply itself. That is up to the caller - * Note that there is no current need to ping. If the server - * breaks the connection then there will be a series of SE_MSG_NONE - * coming on the connection. Receipt of several SE_MSG_NONE can be used - * by clients to realize the connection is broken - * - * if you are looking for a blocking ping test which waits for a ping reply - * then use sysevent_ping_test - */ +/** +* @brief Ping a connection to the sysevent daemon. +* +* @param[in] fd - The file descriptor to ping. +* @param[in] token - Server provided opaque value. +* +* @return Status of the operation. +* @retval 0 if ping message sent successfully. +* @retval Non-zero on error. +* +* @note We only told sysevent daemon to ping reply. We are not handling the +* reply itself. That is up to the caller. Note that there is no current need +* to ping. If the server breaks the connection then there will be a series of +* SE_MSG_NONE coming on the connection. Receipt of several SE_MSG_NONE can be +* used by clients to realize the connection is broken. If you are looking for a +* blocking ping test which waits for a ping reply then use sysevent_ping_test. +*/ int sysevent_ping (int fd, token_t token); -/* - * Procedure : sysevent_ping_test - * Purpose : Ping a connection to the sysevent daemon - * AND wait for reply - * Parameters : - * fd : the file descriptor to ping - * token : Server provided opaque value - * tv : A timeval describing how long to wait - * Return Code : - * 0 : ping reply msg received - * !0 : some error - */ +/** +* @brief Ping a connection to the sysevent daemon and wait for reply. +* +* @param[in] fd - The file descriptor to ping. +* @param[in] token - Server provided opaque value. +* @param[in] tv - Pointer to a timeval structure describing how long to wait. +* +* @return Status of the operation. +* @retval 0 if ping reply message received. +* @retval Non-zero on error. +* +*/ int sysevent_ping_test (int fd, token_t token, struct timeval* tv); - -/* - * Procedure : sysevent_get - * Purpose : Send a get to the sysevent daemon and receive reply - * Parameters : - * fd the connection descriptor - * token : The server provided opaque id of the client - * inbuf : A null terminated string which is the thing to get - * outbuf : A buffer to hold returned value - * outbytes : The maximum number of bytes in outbuf - * Return Code : - * 0 : Reply received - * !0 : Some error - * Notes : - * If outbuf is not big enough to hold the reply value, then the value will - * be truncated to fit. An error of ERR_INSUFFICIENT_ROOM will be returned. - * The value will always be NULL terminated, so the outbuf must contain - * enough bytes for the return value as well as the NULL byte. - */ +/** +* @brief Send a get request to the sysevent daemon and receive reply. +* +* @param[in] fd - The connection descriptor. +* @param[in] token - The server provided opaque id of the client. +* @param[in] inbuf - A null terminated string which is the thing to get. +* @param[out] outbuf - A buffer to hold returned value. +* @param[in] outbytes - The maximum number of bytes in outbuf. +* +* @return Status of the operation. +* @retval 0 if reply received. +* @retval Non-zero on error. +* +* @note If outbuf is not big enough to hold the reply value, then the value will +* be truncated to fit. An error of ERR_INSUFFICIENT_ROOM will be returned. +* The value will always be NULL terminated, so the outbuf must contain enough bytes +* for the return value as well as the NULL byte. +*/ int sysevent_get(const int fd, const token_t token, const char *inbuf, char *outbuf, int outbytes); -/* - * Procedure : sysevent_get_data - * Purpose : Send a get to the sysevent daemon and receive reply - * Parameters : - * fd : The connection id - * token : Server provided opaque value - * inbuf : A null terminated string which is the thing to get - * inbytes : The length of the string not counting terminating null - * outbuf : A buffer to hold returned value - * outbytes : The maximum number of bytes in outbuf - * bufsizecopied : The actual number of bytes copied into outbuf - * Return Code : - * 0 : Reply received - * !0 : Some error - * Notes : - * If outbuf is not big enough to hold the reply value, then the value will - * be truncated to fit. An error of ERR_INSUFFICIENT_ROOM will be returned. - * The value will always be NULL terminated, so the outbuf must contain - * enough bytes for the return value as well as the NULL byte. - */ +/** +* @brief Send a get request for binary data to the sysevent daemon and receive reply. +* +* @param[in] fd - The connection id. +* @param[in] token - Server provided opaque value. +* @param[in] inbuf - A null terminated string which is the thing to get. +* @param[out] outbuf - A buffer to hold returned value. +* @param[in] outbytes - The maximum number of bytes in outbuf. +* @param[out] actualsizecopied - Pointer to store the actual number of bytes copied into outbuf. +* +* @return Status of the operation. +* @retval 0 if reply received. +* @retval Non-zero on error. +* +* @note If outbuf is not big enough to hold the reply value, then the value will +* be truncated to fit. An error of ERR_INSUFFICIENT_ROOM will be returned.The value +* will always be NULL terminated, so the outbuf must contain enough bytes for the +* return value as well as the NULL byte. +*/ int sysevent_get_data(const int fd, const token_t token, const char *inbuf, char *outbuf, int outbytes,int *actualsizecopied); -/* - * Procedure : sysevent_set - * Purpose : Send a set to the sysevent daemon - * A set may change the value of a tuple - * Parameters : - * fd the connection descriptor - * token : The server provided opaque id of the client - * name : A null terminated string which is the tuple to set - * value : A null terminated string which is the value to set tuple to, or NULL - * Return Code : - * 0 : Success - * !0 : Some error - */ - +/** +* @brief Send a set request to the sysevent daemon. +* +* A set may change the value of a tuple. +* +* @param[in] fd - The connection descriptor. +* @param[in] token - The server provided opaque id of the client. +* @param[in] name - A null terminated string which is the tuple to set. +* @param[in] value - A null terminated string which is the value to set tuple to, or NULL. +* @param[in] conf_req - Configuration request flag. +* +* @return Status of the operation. +* @retval 0 on success. +* @retval Non-zero on error. +*/ int sysevent_set(const int fd, const token_t token, const char *name, const char *value, int conf_req); -/* - * Procedure : sysevent_set_data - * Purpose : Send a set to the sysevent daemon - * A set may change the value of a tuple - * Parameters : - * fd : The connection id - * token : Server provided opaque value - * name : A null terminated string which is the tuple to set - * value : buffer holds binary data which is the value to set tuple to, or NULL - * value_length : actual size of binary data buffer - * Return Code : - * 0 : Reply received - * !0 : Some error - */ +/** +* @brief Send a set request with binary data to the sysevent daemon. +* +* This function send a set to the sysevent daemon. A set may change the value of a tuple. +* +* @param[in] fd - The connection id. +* @param[in] token - Server provided opaque value. +* @param[in] name - A null terminated string which is the tuple to set. +* @param[in] value - Buffer holding binary data which is the value to set tuple to, or NULL. +* @param[in] value_length - Actual size of binary data buffer. +* +* @return Status of the operation. +* @retval 0 if reply received. +* @retval Non-zero on error. +*/ int sysevent_set_data(const int fd, const token_t token, const char *name, const char *value, int value_length); -/* - * Procedure : sysevent_unset - * Purpose : Send a set to the sysevent daemon - * A set with NULL value of a tuple to clear existing value from volatile memory. - * Parameters : - * fd : The connection id - * token : Server provided opaque value - * name : A null terminated string which is the tuple to set - * value : NULL by default - * Return Code : - * 0 : Reply received - * !0 : Some error - */ +/** +* @brief Send a set request with NULL value to clear existing tuple value from volatile memory. +* +* Send a set to the sysevent daemon. A set with NULL value of a tuple to clear existing value from volatile memory. +* +* @param[in] fd - The connection id. +* @param[in] token - Server provided opaque value. +* @param[in] name - A null terminated string which is the tuple to set. +* +* @return Status of the operation. +* @retval 0 if reply received. +* @retval Non-zero on error. +*/ int sysevent_unset (const int fd, const token_t token, const char *name); - -/* - * Procedure : sysevent_set_with_tid - * Purpose : Send a set to the sysevent daemon - * A set may change the value of a tuple - * Parameters : - * fd : The connection id - * token : Server provided opaque value - * name : A null terminated string which is the tuple to set - * value : A null terminated string which is the value to set tuple to, or NULL - * source : source of message - * tid : transaction id - * Return Code : - * 0 : Success - * !0 : Some error - */ +/** +* @brief Send a set request with transaction ID to the sysevent daemon. +* +* Send a set to the sysevent daemon. A set may change the value of a tuple. +* +* @param[in] fd - The connection descriptor. +* @param[in] token - Server provided opaque value. +* @param[in] name - A null terminated string which is the tuple to set. +* @param[in] value - A null terminated string which is the value to set tuple to, or NULL. +* @param[in] source - Source of message. +* @param[in] tid - Transaction id. +* +* @return Status of the operation. +* @retval 0 on success. +* @retval Non-zero on error. +*/ int sysevent_set_with_tid (const int fd, const token_t token, const char *name, const char *value, const int source, const int tid); - -/* - * Procedure : sysevent_set_unique - * Purpose : Send a set unique to the sysevent daemon and receive reply - * A set will create a new tuple with name derived from client request, - * and it will set this new tuple to the value. - * Parameters : - * fd the connection descriptor - * token : The server provided opaque id of the client - * name : A null terminated string which is the namespace of the tuple to create and set - * value : A null terminated string which is the value to set tuple to, or NULL - * outbuf : A buffer to hold returned value - * outbytes : The maximum number of bytes in outbuf - * Return Code : - * 0 : Reply received - * !0 : Some error - * Note that the position of the newly added item within its namespace is not guaranteed to be - * in a particular order when iterating through the space using sysevent_get_unique. - * If you need to guarantee that the newly added item is iterated in order of its addition to the - * namespace (and are willing to cost the system some memory for each element in the namespace) then - * you must use the ! character as the first character in your namespace - */ +/** +* @brief Send a set unique request to the sysevent daemon and receive reply. +* +* A set will create a new tuple with name derived from client request, and it will set this new tuple to the value. +* Send a set unique to the sysevent daemon. +* +* @param[in] fd - The connection descriptor. +* @param[in] token - The server provided opaque id of the client. +* @param[in] name - A null terminated string which is the namespace of the tuple to create and set. +* @param[in] value - A null terminated string which is the value to set tuple to, or NULL. +* @param[out] outbuf - A buffer to hold returned unique tuple name. +* @param[in] outbytes - The maximum number of bytes in outbuf. +* +* @return Status of the operation. +* @retval 0 if reply received. +* @retval Non-zero on error. +* +* @note the position of the newly added item within its namespace is not guaranteed to be +* in a particular order when iterating through the space using sysevent_get_unique. +* If you need to guarantee that the newly added item is iterated in order of its addition to the +* namespace (and are willing to cost the system some memory for each element in the namespace) then +* you must use the ! character as the first character in your namespace +*/ int sysevent_set_unique(const int fd, const token_t token, const char *name, const char *value, char *outbuf, int outbytes); -/* - * Procedure : sysevent_get_unique - * Purpose : Send a get for a unique element to the sysevent daemon and receive reply - * This returns the next value. - * Parameters : - * fd the connection descriptor - * token : The server provided opaque id of the client - * inbuf : A null terminated string which is the namespace of the thing to get - * iterator : A iterator which is initialize to NULL - * on return it will contain the next iterator - * subjectbuf : A buffer to hold returned unique name - * subjectbytes : The maximum number of bytes in subjectbuf - * valuebuf : A buffer to hold returned value - * valuebytes : The maximum number of bytes in valuebuf - * Return Code : - * 0 : Reply received - * !0 : Some error - * Notes : - * If either is not big enough to hold the reply value, then the value will - * be truncated to fit. An error of ERR_INSUFFICIENT_ROOM will be returned. - * The value will always be NULL terminated, so the outbuf must contain - * enough bytes for the return value as well as the NULL byte. - */ +/** +* @brief Send a get request for a unique element to the sysevent daemon and receive reply. +* +* This function send to the sysevent daemon and receive reply +* +* @param[in] fd - The connection descriptor. +* @param[in] token - The server provided opaque id of the client. +* @param[in] inbuf - A null terminated string which is the namespace of the thing to get. +* @param[in,out] iterator - A iterator which is initialized to NULL. +* @param[out] subjectbuf - A buffer to hold returned unique name. +* @param[in] subjectbytes - The maximum number of bytes in subjectbuf. +* @param[out] valuebuf - A buffer to hold returned value. +* @param[in] valuebytes - The maximum number of bytes in valuebuf. +* +* @return Status of the operation. +* @retval 0 if reply received. +* @retval Non-zero on error. +* +* @note If either is not big enough to hold the reply value, then the value will +* be truncated to fit. An error of ERR_INSUFFICIENT_ROOM will be returned. +* The value will always be NULL terminated, so the outbuf must contain +* enough bytes for the return value as well as the NULL byte. +*/ int sysevent_get_unique(const int fd, const token_t token, const char *inbuf, unsigned int *iterator, char *subjectbuf, int subjectbytes, char *valuebuf, int valuebytes); -/* - * Procedure : sysevent_del_unique - * Purpose : Send a delete of unique element from its namespace - * Parameters : - * fd the connection descriptor - * token : The server provided opaque id of the client - * inbuf : A null terminated string which is the namespace of the thing to delete - * iterator : A iterator which is describing the element to delete within the namespace - * The first iterator is SYSEVENT_NULL_ITERATOR - * Return Code : - * 0 : - */ +/** +* @brief Send a delete request for a unique element from its namespace. +* +* @param[in] fd - The connection descriptor. +* @param[in] token - The server provided opaque id of the client. +* @param[in] inbuf - A null terminated string which is the namespace of the thing to delete. +* @param[in,out] iterator - A iterator which is describing the element to delete within the namespace. +* \n The first iterator is SYSEVENT_NULL_ITERATOR +* +* @return Status of the operation. +* @retval 0 on success. +* @retval Non-zero on error. +*/ int sysevent_del_unique(const int fd, const token_t token, const char *inbuf, unsigned int *iterator); -/* - * Procedure : sysevent_get_next_iterator - * Purpose : Get the next iterator for a namespace - * Parameters : - * fd the connection descriptor - * token : The server provided opaque id of the client - * inbuf : A null terminated string which is the namespace - * iterator : A iterator which is describing the current iterator. Initially set to 0 - * On return it contains the next iterator to the namespace - * Return Code : - * 0 : - */ +/** +* @brief Get the next iterator for a namespace. +* +* @param[in] fd - The connection descriptor. +* @param[in] token - The server provided opaque id of the client. +* @param[in] inbuf - A null terminated string which is the namespace. +* @param[in,out] iterator - A iterator which is describing the current iterator. Initially set to 0. +* On return it contains the next iterator to the namespace. +* +* @return Status of the operation. +* @retval 0 on success. +* @retval Non-zero on error. +*/ int sysevent_get_next_iterator(const int fd, const token_t token, const char *inbuf, unsigned int *iterator); -/* - * Procedure : sysevent_set_options - * Purpose : Send a set options flag to the sysevent daemon and receive reply - * A set may change the event flags of that tuple - * Parameters : - * fd the connection descriptor - * token : The server provided opaque id of the client - * name : A null terminated string which is the tuple to set - * flags : The flags to set tuple to - * Return Code : - * 0 : Success - * !0 : Some error - */ +/** +* @brief Send a set options flag request to the sysevent daemon and receive reply. +* +* A set may change the event flags of that tuple. +* +* @param[in] fd - The connection descriptor. +* @param[in] token - The server provided opaque id of the client. +* @param[in] name - A null terminated string which is the tuple to set. +* @param[in] flags - The flags to set tuple to. +* +* @return Status of the operation. +* @retval 0 on success. +* @retval Non-zero on error. +*/ int sysevent_set_options(const int fd, const token_t token, const char *name, unsigned int flags); -/* - * Procedure : sysevent_setcallback - * Purpose : Declare a program to run when a given tuple changes value - * Parameters : - * fd the connection descriptor - * token : The server provided opaque id of the client - * flags : action_flag_t flags to control the activation - * subject : A null terminated string which is the name of the tuple - * function : An execeutable to call when the tuple changes value - * numparams : The number of arguments in the following char** - * params : A list of 0 or more parameters to use when calling the function - * async_id : On return, and id that can be used to cancel the callback - * Return Code : - * 0 : Success - * !0 : Some error - * Notes : - * When the tuple changes value the executabl3 will be called with all parameters given - * the value of parameters will be either: - * the exact string given as a parameter, or - * if the parameter begins with $ the return will be the current value - * of the trigger by that name. If the trigger does not exist - * then "NULL" will be used. - * For example, if the subject is trigger1, the function /bin/programA, and - * the parameter list is 3 params = trigger1, $trigger3, $trigger1. - * Assuming trigger3 has not yet been set, - * Then when trigger1 changes to "new_value", a process will be forked to - * call /bin/programA "trigger1" "NULL" "new_value" - */ +/** +* @brief Declare a program to run when a given tuple changes value. +* +* @param[in] fd - The connection descriptor. +* @param[in] token - The server provided opaque id of the client. +* @param[in] flags - action_flag_t flags to control the activation. +* @param[in] subject - A null terminated string which is the name of the tuple. +* @param[in] function - An executable to call when the tuple changes value. +* @param[in] numparams - The number of arguments in the following char**. +* @param[in] params - A list of 0 or more parameters to use when calling the function. +* @param[out] async_id - On return, an id that can be used to cancel the callback. +* +* @return Status of the operation. +* @retval 0 on success. +* @retval Non-zero on error. +* +* @note When the tuple changes value, the executable will be called with all parameters given. +* The value of parameters will be either: the exact string given as a parameter, or if the +* parameter begins with $ the return will be the current value of the trigger by that name. +* If the trigger does not exist then "NULL" will be used. +* For example, if the subject is trigger1, the function /bin/programA, and the parameter +* list is 3 params = trigger1, $trigger3, $trigger1. Assuming trigger3 has not yet been set, +* Then when trigger1 changes to "new_value", a process will be forked to +* call /bin/programA "trigger1" "NULL" "new_value". +*/ int sysevent_setcallback(const int fd, const token_t token, action_flag_t flags, char *subject, char *function, int numparams, char **params, async_id_t *async_id); -/* - * Procedure : sysevent_rmcallback - * Purpose : Remove an callback/notification from a trigger - * Parameters : - * fd the connection descriptor - * token : The server provided opaque id of the client - * async_id : The async id to remove - * Return Code : - * 0 : Async action is removed - */ +/** +* @brief Remove a callback/notification from a trigger. +* +* @param[in] fd - The connection descriptor. +* @param[in] token - The server provided opaque id of the client. +* @param[in] async_id - The async id to remove. +* +* @return Status of the operation. +* @retval 0 if async action is removed. +* @retval Non-zero on error. +*/ int sysevent_rmcallback(const int fd, const token_t token, async_id_t async_id); -/* - * Procedure : sysevent_setnotification - * Purpose : Request a notification message to be sent when a given tuple changes value - * Parameters : - * fd : the connection descriptor - * token : The server provided opaque id of the client - * subject : A null terminated string which is the name of the tuple - * async_id : On return, and id that can be used to cancel the notification - * Return Code : - * 0 : Success - * !0 : Some error - * Note : A notification can only be sent to a client which is still connected - * Note : Notifications are asynchronous and should be sent to a client connection - * which is dedicated to asynchronous sysevent messages. In other words a - * connection which is not shared with a thread doing sets/gets etc. - */ +/** +* @brief Request a notification message to be sent when a given tuple changes value. +* +* A notification can only be sent to a client which is still connected. +* +* @param[in] fd - The connection descriptor. +* @param[in] token - The server provided opaque id of the client. +* @param[in] subject - A null terminated string which is the name of the tuple. +* @param[out] async_id - On return, an id that can be used to cancel the notification. +* +* @return Status of the operation. +* @retval 0 on success. +* @retval Non-zero on error. +* +* @note Notifications are asynchronous and should be sent to a client connection +* which is dedicated to asynchronous sysevent messages. In other words a +* connection which is not shared with a thread doing sets/gets etc. +*/ int sysevent_setnotification(const int fd, const token_t token, char *subject, async_id_t *async_id); -/* - * Procedure : sysevent_rmnotification - * Purpose : Remove an callback/notification from a trigger - * Parameters : - * fd the connection descriptor - * token : The server provided opaque id of the client - * async_id : The async id to remove - * Return Code : - * 0 : Async action is removed - */ +/** +* @brief Remove a callback/notification from a trigger. +* +* @param[in] fd - The connection descriptor. +* @param[in] token - The server provided opaque id of the client. +* @param[in] async_id - The async id to remove. +* +* @return Status of the operation. +* @retval 0 if async action is removed. +* @retval Non-zero on error. +*/ int sysevent_rmnotification(const int fd, const token_t token, async_id_t async_id); -/* - * Procedure : sysevent_getnotification - * Purpose : Wait for a notification and return the results when received - * Parameters : - * fd : The connection id - * token : The server provided opaque id of the client - * namebuf : A buffer to hold the name received - * namebytes : The length of the string not counting terminating null - * valbuf : A buffer to hold returned value - * valbytes : On input the maximum number of bytes in outbuf - * On output the actual number of bytes in outbuf not counting - * the terminating null - * async_id : The async id of the action - * Return Code : - * 0 : Reply received - * !0 : Some error - * Notes : - * If a buffer is not big enough to hold the reply value, then the value will - * be truncated to fit. An error of ERR_INSUFFICIENT_ROOM will be returned. - * The value will always be NULL terminated, so the buffer must contain - * enough bytes for the return value as well as the NULL byte. - * Notes - * This will block - */ +/** +* @brief Wait for a notification and return the results when received. +* +* @param[in] fd - The connection descriptor. +* @param[in] token - The server provided opaque id of the client. +* @param[out] namebuf - A buffer to hold the name received. +* @param[in,out] namebytes - On input, the maximum length of the string not counting terminating null. +* On output, the actual length of the string not counting terminating null. +* @param[out] valbuf - A buffer to hold returned value. +* @param[in,out] valbytes - On input, the maximum number of bytes in valbuf. +* On output, the actual number of bytes in valbuf not counting the terminating null. +* @param[out] async_id - The async id of the action. +* +* @return Status of the operation. +* @retval 0 if reply received. +* @retval Non-zero on error. +* +* @note If a buffer is not big enough to hold the reply value, then the value will +* be truncated to fit. An error of ERR_INSUFFICIENT_ROOM will be returned. The value +* will always be NULL terminated, so the buffer must contain enough bytes for the +* return value as well as the NULL byte. This will block +*/ int sysevent_getnotification (const int fd, const token_t token, char *namebuf, int *namebytes, char *valbuf, int *valbytes, async_id_t *async_id); -/* - * Procedure : sysevent_getnotification_data - * Purpose : Wait for a notification and return the results when received - * Parameters : - * fd : The connection id - * token : A server generated opaque value - * namebuf : A buffer to hold the name received - * namebytes : The length of the string not counting terminating null - * valbuf : A buffer to hold returned value - * valbytes : On input the maximum number of bytes in outbuf - * On output the actual number of bytes in outbuf - * async_id : The async id of the action - * Return Code : - * 0 : Reply received - * !0 : Some error - * Notes : - * If a buffer is not big enough to hold the reply value, then the value will - * be truncated to fit. An error of ERR_INSUFFICIENT_ROOM will be returned. - * The value will always be NULL terminated, so the buffer must contain - * enough bytes for the return value as well as the NULL byte. - * Notes - * This will block - */ +/** +* @brief Wait for a notification with binary data and return the results when received. +* +* @param[in] fd - The connection descriptor. +* @param[in] token - A server generated opaque value. +* @param[out] namebuf - A buffer to hold the name received. +* @param[in,out] namebytes - On input, the maximum length of the string not counting terminating null. +* On output, the actual length of the string not counting terminating null. +* @param[out] valbuf - A buffer to hold returned binary value. +* @param[in,out] valbytes - On input, the maximum number of bytes in valbuf. +* On output, the actual number of bytes in valbuf. +* @param[out] async_id - The async id of the action. +* +* @return Status of the operation. +* @retval 0 if reply received. +* @retval Non-zero on error. +* +* @note If a buffer is not big enough to hold the reply value, then the value will +* be truncated to fit. An error of ERR_INSUFFICIENT_ROOM will be returned. The value +* will always be NULL terminated, so the buffer must contain enough bytes for the +* return value as well as the NULL byte. This will block +*/ int sysevent_getnotification_data (const int fd, const token_t token, char *namebuf, int *namebytes, char *valbuf, int *valbytes, async_id_t *async_id); -/* - * Procedure : sysevent_show - * Purpose : Tell daemon to show all data elements - * Parameters : - * fd : The connection id - * token : The server provided opaque id of the client - * file : A null terminated string which is the file to write to - * Return Code : - * 0 : Success - * !0 : Some error - */ +/** +* @brief Tell daemon to show all data elements. +* +* @param[in] fd - The connection descriptor. +* @param[in] token - The server provided opaque id of the client. +* @param[in] file - A null terminated string which is the file to write to. +* +* @return Status of the operation. +* @retval 0 on success. +* @retval Non-zero on error. +*/ int sysevent_show (const int fd, const token_t token, const char *file); -/* - * Procedure : sysevent_debug - * Purpose : Set sysevent daemon debug level - * Parameters : - * ip : the name or ip address of the sysevent daemon to send msg to - * port : the port of the sysevent daemon to send to - * level : Debug level to set to - * Return Code : - * 0 : debug msg sent - * !0 : some error - */ +/** +* @brief Set sysevent daemon debug level. +* +* @param[in] ip - The name or IP address of the sysevent daemon to send message to. +* @param[in] port - The port of the sysevent daemon to send to. +* @param[in] level - Debug level to set to. +* +* @return Status of the operation. +* @retval 0 if debug message sent. +* @retval Non-zero on error. +*/ int sysevent_debug (char *ip, unsigned short port, int level); +/** +* @brief Get the maximum size for binary message data. +* +* @return Maximum size in bytes for binary message data. +*/ unsigned int sysevent_get_binmsg_maxsize(); #ifdef __cplusplus diff --git a/source/include/ulog/ulog.h b/source/include/ulog/ulog.h index bd7ffafd..b2920862 100644 --- a/source/include/ulog/ulog.h +++ b/source/include/ulog/ulog.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -54,7 +54,7 @@ typedef struct _sys_log_info{ pid_t pid; // process ID int gPrior; // global log priority int prior; // log priority - unsigned int enable; // logging enabled + unsigned int enable; // logging enabled FILE* stream; // stream of log file }_sys_Log_Info; @@ -68,13 +68,92 @@ typedef struct _sys_log_info{ #define ulog_LOG_Info(format, ...) ulog_sys(LOG_INFO, __FILE__, __LINE__, format, ##__VA_ARGS__) #define ulog_LOG_Dbg(format, ...) ulog_sys(LOG_DEBUG, __FILE__, __LINE__, format, ##__VA_ARGS__) +/** +* @brief Get the global log priority level. +* +* @return The global priority level. +* @retval priority level on success. +* @retval -1 if no priority level is set. +*/ int ulog_GetGlobalPrior(void); + +/** +* @brief Set the global log priority level. +* +* Sets the log mask up to the specified priority level using setlogmask. +* +* @param[in] prior - Priority level to set. +* +* @return None. +*/ void ulog_SetGlobalPrior(int prior); + +/** +* @brief Get the current log priority level. +* +* @return The current log priority level. +*/ int ulog_GetPrior(void); + +/** +* @brief Set the current log priority level. +* +* @param[in] prior - Priority level to set. If priority is out of valid range, +* the function returns without setting. +* +* @return None. +* +*/ void ulog_SetPrior(int prior); + +/** +* @brief Get the current process ID and name. +* +* Retrieves the process ID and process name by reading /proc/pid/stat file. +* +* @param[in] size - Size of the name buffer. +* @param[out] name - Buffer to store the process name. +* @param[out] pid - Pointer to store the process ID. +* +* @return Status of the operation. +* @retval 0 on success. +* @retval -1 if size is 0, name or pid is NULL, or unable to read process information. +* +*/ int ulog_GetProcId(size_t size, char *name, pid_t *pid); + +/** +* @brief Get the logging enable status. +* +* @return The current logging enable status. +* @retval 1 if logging is enabled. +* @retval 0 if logging is disabled. +*/ unsigned int ulog_GetEnable(void); + +/** +* @brief Set the logging enable status. +* +* @param[in] enable - Enable flag (1 to enable, 0 to disable). +* +* @return None. +*/ void ulog_SetEnable(unsigned int enable); + +/** +* @brief Log a message to system logger with file and line information. +* +* Logs messages to syslog with timestamp, file name, and line number information. +* +* @param[in] prior - Priority level. +* @param[in] fileName - Source file name where log is generated. +* @param[in] line - Line number in source file where log is generated. +* @param[in] format - Printf-style format string. +* @param[in] ... - Variable arguments for format string. +* +* @return None. +* +*/ void ulog_sys(int prior, const char* fileName, int line, const char* format, ...); typedef enum { @@ -97,7 +176,7 @@ typedef enum { /* SYSTEM */ UL_SYSEVENT, UL_SYSCFG, - UL_UTCTX, + UL_UTCTX, /* LAN */ UL_DHCPSERVER, /* WAN */ @@ -121,137 +200,139 @@ typedef enum { } USUBCOMP; -/* - * Procedure : ulog_init - * Purpose : Per process initialization of logging infrastruture - * Parameters : None - * Return Values : None - * Notes : - * Opens connect to system logget and sets up a prefix string - * Current prefix string is "UTOPIA: " - */ +/** +* @brief Per process initialization of logging infrastructure. +* +* Opens connection to system logger and sets up a prefix string. +* +* @return None. +* +* @note Opens connect to system logget and sets up a prefix string. +* Current prefix string is "UTOPIA:" +*/ void ulog_init(); -/* - * Procedure : ulog - * Purpose : Log a general message to system logger - * Parameters : - * UCOMP - component id - * USUBCOMP - subcomponent id - * mesg - message string - * Return Values : None - * Notes : - * uses syslog LOCAL7.NOTICE facility - */ +/** +* @brief Log a general message to system logger. +* +* @param[in] comp - Component id. +* @param[in] sub - Subcomponent id. +* @param[in] mesg - Message string to log. +* +* @return None. +* +* @note uses syslog LOCAL7.NOTICE facility. +*/ void ulog (UCOMP comp, USUBCOMP sub, const char *mesg); -/* - * Procedure : ulogf - * Purpose : Log a message to system logger with variable arg - * Parameters : - * UCOMP - component id - * USUBCOMP - subcomponent id - * fmt - format of message string - * ... - variable args format for message string - * Return Values : None - * Notes : - * uses syslog LOCAL7.NOTICE facility - */ +/** +* @brief Log a message to system logger with variable arguments. +* +* @param[in] comp - Component id. +* @param[in] sub - Subcomponent id. +* @param[in] fmt - Printf-style format string for message. +* @param[in] ... - Variable arguments for format string. +* +* @return None. +* +* @note uses syslog LOCAL7.NOTICE facility. +*/ void ulogf (UCOMP comp, USUBCOMP sub, const char *fmt, ...); -/* - * Procedure : ulog_debug - * Purpose : Log a debug message to system logger - * Parameters : - * UCOMP - component id - * USUBCOMP - subcomponent id - * mesg - message string - * Return Values : None - * Notes : - * uses syslog LOCAL7.DEBUG facility - */ +/** +* @brief Log a debug message to system logger. +* +* @param[in] comp - Component id. +* @param[in] sub - Subcomponent id. +* @param[in] mesg - Debug message string to log. +* +* @return None. +* +* @note uses syslog LOCAL7.DEBUG facility. +*/ void ulog_debug (UCOMP comp, USUBCOMP sub, const char *mesg); -/* - * Procedure : ulog_debugf - * Purpose : Log debug message to system logger with variable arg - * Parameters : - * UCOMP - component id - * USUBCOMP - subcomponent id - * fmt - format of message string - * ... - variable args format for message string - * Return Values : None - * Notes : - * uses syslog LOCAL7.DEBUG facility - */ +/** +* @brief Log a debug message to system logger with variable arguments. +* +* @param[in] comp - Component id. +* @param[in] sub - Subcomponent id. +* @param[in] fmt - Printf-style format string for debug message. +* @param[in] ... - Variable arguments for format string. +* +* @return None. +* +* @note uses syslog LOCAL7.DEBUG facility. +*/ void ulog_debugf (UCOMP comp, USUBCOMP sub, const char *fmt, ...); -/* - * Procedure : ulog_error - * Purpose : Log an error message to system logger - * Parameters : - * UCOMP - component id - * USUBCOMP - subcomponent id - * mesg - message string - * Return Values : None - * Notes : - * uses syslog LOCAL7.ERROR facility - */ +/** +* @brief Log an error message to system logger. +* +* @param[in] comp - Component id. +* @param[in] sub - Subcomponent id. +* @param[in] mesg - Error message string to log. +* +* @return None. +* +* @note uses syslog LOCAL7.ERROR facility. +*/ void ulog_error (UCOMP comp, USUBCOMP sub, const char *mesg); -/* - * Procedure : ulog_errorf - * Purpose : Log error message to system logger with variable arg - * Parameters : - * UCOMP - component id - * USUBCOMP - subcomponent id - * mesg - message string - * Return Values : None - * Notes : - * uses syslog LOCAL7.ERR facility - */ +/** +* @brief Log an error message to system logger with variable arguments. +* +* @param[in] comp - Component id. +* @param[in] sub - Subcomponent id. +* @param[in] fmt - Printf-style format string for error message. +* @param[in] ... - Variable arguments for format string. +* +* @return None. +* +* @note uses syslog LOCAL7.ERROR facility. +*/ void ulog_errorf (UCOMP comp, USUBCOMP sub, const char *fmt, ...); -/* - * Procedure : ulog_get_mesgs - * Purpose : Retrieve mesgs for given component.subcomponent - * Parameters : - * UCOMP - component id - * USUBCOMP - subcomponent id - * mesgbuf - message strings output buffer - * size - size of above buffer - * Return Values : None - * Notes : - * mesgbuf will be truncated before mesgs are stored, - * and upto allowed size - */ +/** +* @brief Retrieve messages for given component.subcomponent. +* +* @param[in] comp - Component id. +* @param[in] sub - Subcomponent id. +* @param[out] mesgbuf - Buffer to hold retrieved message strings. +* @param[in] size - Size of the message buffer. +* +* @return None. +* +* @note mesgbuf will be truncated before mesgs are stored, and upto allowed size. +*/ void ulog_get_mesgs (UCOMP comp, USUBCOMP sub, char *mesgbuf, unsigned int size); #if 0 -/* - * Procedure : ulog_runcmd - * Purpose : Log and run command string - * Parameters : - * UCOMP - component id - * USUBCOMP - subcomponent id - * cmd - command string - * Return Values : None - * Notes : - * uses syslog LOCAL7.NOTICE facility - */ +/** +* @brief Log and run command string. +* +* @param[in] comp - Component id. +* @param[in] sub - Subcomponent id. +* @param[in] cmd - Command string to execute. +* +* @return None. +* +* @note uses syslog LOCAL7.NOTICE facility +*/ void ulog_runcmd (UCOMP comp, USUBCOMP sub, const char *cmd); -/* - * Procedure : ulog_runcmdf - * Purpose : Log and run command string with variable arg - * Parameters : - * UCOMP - component id - * USUBCOMP - subcomponent id - * mesg - message string - * Return Values : None - * Notes : - * uses syslog LOCAL7.NOTICE facility - */ +/** +* @brief Log and run command string with variable arguments. +* +* @param[in] comp - Component id. +* @param[in] sub - Subcomponent id. +* @param[in] fmt - Printf-style format string for command. +* @param[in] ... - Variable arguments for format string. +* +* @return Status of the command execution. +* +* @note uses syslog LOCAL7.NOTICE facility +*/ int ulog_runcmdf (UCOMP comp, USUBCOMP sub, const char *fmt, ...); #endif diff --git a/source/include/utapi/utapi.h b/source/include/utapi/utapi.h index 0b960dce..03df17d2 100644 --- a/source/include/utapi/utapi.h +++ b/source/include/utapi/utapi.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -65,7 +65,7 @@ typedef int token_t; /* * General */ - + typedef char* String; typedef int boolean_t; @@ -81,8 +81,8 @@ typedef int boolean_t; #define IPHOSTNAME_SZ 128 // hostname foo.domain.com or IP address #define PORT_SZ 6 // port number 0 - 65535 #define URL_SZ 512 // http://foo.domain.com/blahblah -#define IFNAME_SZ 16 // size of interface names like br0, vlan2, eth3 -#define TOKEN_SZ 128 // generic token +#define IFNAME_SZ 16 // size of interface names like br0, vlan2, eth3 +#define TOKEN_SZ 128 // generic token #define USERNAME_SZ 64 #define PASSWORD_SZ 64 #define WAN_SERVICE_NAME_SZ 64 @@ -129,7 +129,7 @@ typedef int boolean_t; typedef struct { unsigned int magic; unsigned int len; - unsigned int version; + unsigned int version; unsigned int crc32; } config_hdr_t; @@ -177,7 +177,7 @@ typedef enum { typedef enum { INTERFACE_LAN, INTERFACE_WAN, -} interface_t; +} interface_t; /* @@ -243,7 +243,7 @@ typedef struct wanInfo { boolean_t auto_mtu; // true - automatically picked, false - set it to size specified int mtu_size; }__attribute__ ((__packed__)) wanInfo_t; - + /* * Router/Bridge settings */ @@ -291,8 +291,8 @@ typedef enum ddnsProvider { DDNS_TZO, DDNS_EASYDNS, DDNS_EASYDNS_PARTNER, - DDNS_GNUDIP, - DDNS_JUSTLINUX, + DDNS_GNUDIP, + DDNS_JUSTLINUX, DDNS_DYNS, DDNS_HN, DDNS_ZONEEDIT, @@ -336,7 +336,7 @@ typedef struct routeStatic { char dest_lan_ip[IPADDR_SZ]; char netmask[IPADDR_SZ]; char gateway[IPADDR_SZ]; - interface_t dest_intf; + interface_t dest_intf; } routeStatic_t; typedef struct routeEntry { @@ -360,13 +360,13 @@ typedef enum protocol { typedef struct portFwdSingle { char name[NAME_SZ]; boolean_t enabled; - boolean_t prevRuleEnabledState; + boolean_t prevRuleEnabledState; int rule_id; protocol_t protocol; int external_port; int internal_port; - char dest_ip[IPADDR_SZ]; - char dest_ipv6[64]; + char dest_ip[IPADDR_SZ]; + char dest_ipv6[64]; } portFwdSingle_t; typedef struct portMapDyn { @@ -384,22 +384,22 @@ typedef struct portMapDyn { typedef struct portFwdRange { char name[NAME_SZ]; boolean_t enabled; - boolean_t prevRuleEnabledState; + boolean_t prevRuleEnabledState; int rule_id; protocol_t protocol; int start_port; int end_port; int internal_port; int internal_port_range_size; - char dest_ip[IPADDR_SZ]; - char dest_ipv6[64]; - char public_ip[IPADDR_SZ]; + char dest_ip[IPADDR_SZ]; + char dest_ipv6[64]; + char public_ip[IPADDR_SZ]; } portFwdRange_t; typedef struct portRangeTrig { char name[TOKEN_SZ]; boolean_t enabled; - boolean_t prevRuleEnabledState; + boolean_t prevRuleEnabledState; int rule_id; protocol_t trigger_proto; protocol_t forward_proto; @@ -561,10 +561,79 @@ typedef struct qosPolicy { } qosPolicy_t; */ +/** +* @brief Get QoS defined policy list. +* +* Returns a list of predefined QoS policies with their default priorities. +* +* @param[out] out_count - Pointer to store count of policies. +* @param[out] out_qoslist - Pointer to receive const array of predefined policies. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval ERR_FILE_NOT_FOUND error on file not found +* @retval Error code on failure. +*/ int Utopia_GetQoSDefinedPolicyList (int *out_count, qosDefinedPolicy_t const **out_qoslist); + +/** +* @brief Set QoS settings. +* +* Configures Quality of Service settings including enable status, policy list, and bandwidth speeds. +* +* @param[in] ctx - Utopia context. +* @param[in] qos - Pointer to qosInfo_t structure containing QoS settings. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +*/ int Utopia_SetQoSSettings (UtopiaContext *ctx, qosInfo_t *qos); + +/** +* @brief Get QoS settings. +* +* @param[in] ctx - Utopia context. +* @param[out] qos - Pointer to qosInfo_t structure to store QoS settings. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +*/ int Utopia_GetQoSSettings (UtopiaContext *ctx, qosInfo_t *qos); + +/** +* @brief Get LAN host comments by MAC address. +* +* Retrieves the comments/description associated with a LAN host identified by MAC address. +* +* @param[in] ctx - Utopia context. +* @param[in] pMac - MAC address of the LAN host. +* @param[out] pComments - Buffer to store comments. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +*/ int Utopia_get_lan_host_comments(UtopiaContext *ctx, unsigned char *pMac, unsigned char *pComments); + +/** +* @brief Set LAN host comments by MAC address. +* +* Associates comments/description with a LAN host identified by MAC address. +* +* @param[in] ctx - Utopia context. +* @param[in] pMac - MAC address of the LAN host. +* @param[in] pComments - Comments to associate with the host. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +*/ int Utopia_set_lan_host_comments(UtopiaContext *ctx, unsigned char *pMac, unsigned char *pComments); /* @@ -679,7 +748,7 @@ typedef struct { typedef enum { LAN_INTERFACE_WIRED, LAN_INTERFACE_WIFI, -} lan_interface_t; +} lan_interface_t; /* * LAN setting @@ -717,16 +786,16 @@ typedef struct dhcpServerInfo { char StaticNameServer1[IPHOSTNAME_SZ]; char StaticNameServer2[IPHOSTNAME_SZ]; char StaticNameServer3[IPHOSTNAME_SZ]; - char WINSServer[IPHOSTNAME_SZ]; + char WINSServer[IPHOSTNAME_SZ]; } dhcpServerInfo_t; typedef struct dmz { boolean_t enabled; char source_ip_start[IPADDR_SZ]; // empty string means "any ip address" - char source_ip_end[IPADDR_SZ]; + char source_ip_end[IPADDR_SZ]; //int dest_ip; // last octet char dest_ip[IPADDR_SZ]; // full ip - char dest_mac[MACADDR_SZ]; + char dest_mac[MACADDR_SZ]; char dest_ipv6[64]; } dmz_t; @@ -739,31 +808,214 @@ typedef struct dmz { * Device Settings */ +/** +* @brief Get device settings. +* +* Retrieves device configuration like hostname, language, timezone, and auto DST settings. +* +* @param[in] ctx - Utopia context. +* @param[out] device - Pointer to deviceSetting_t structure to store device settings. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +*/ int Utopia_GetDeviceSettings (UtopiaContext *ctx, deviceSetting_t *device); + +/** +* @brief Set device settings. +* +* Configures device settings like hostname, language, timezone, and auto DST settings. +* +* @param[in] ctx - Utopia context. +* @param[in] device - Pointer to deviceSetting_t structure containing device settings to set. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +*/ int Utopia_SetDeviceSettings (UtopiaContext *ctx, deviceSetting_t *device); /* * LAN Settings */ +/** +* @brief Get LAN settings. +* +* Retrieves LAN configuration like IP address, netmask, domain, MAC address, and interface name. +* +* @param[in] ctx - Utopia context. +* @param[out] lan - Pointer to lanSetting_t structure to store LAN settings. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +*/ int Utopia_GetLanSettings (UtopiaContext *ctx, lanSetting_t *lan); -int Utopia_SetLanSettings(UtopiaContext *ctx, lanSetting_t *lan); +/** +* @brief Set LAN settings. +* +* Configures LAN settings like IP address, netmask, domain. +* +* @param[in] ctx - Utopia context. +* @param[in] lan - Pointer to lanSetting_t structure containing LAN settings to set. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +*/ +int Utopia_SetLanSettings(UtopiaContext *ctx, lanSetting_t *lan); -int Utopia_SetDHCPServerSettings (UtopiaContext *ctx, dhcpServerInfo_t *dhcps); +/** +* @brief Set DHCP server settings. +* +* Configures DHCP server parameters like IP address range, lease time, and DNS servers. +* +* @param[in] ctx - Utopia context. +* @param[in] dhcps - Pointer to dhcpServerInfo_t structure containing DHCP server settings. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +*/ +int Utopia_SetDHCPServerSettings (UtopiaContext *ctx, dhcpServerInfo_t *dhcps); + +/** +* @brief Get DHCP server settings. +* +* Retrieves DHCP server configuration like IP address range, lease time, and DNS servers. +* +* @param[in] ctx - Utopia context. +* @param[out] out_dhcps - Pointer to dhcpServerInfo_t structure to store DHCP server settings. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +*/ int Utopia_GetDHCPServerSettings (UtopiaContext *ctx, dhcpServerInfo_t *out_dhcps); - +/** +* @brief Set DHCP server static host mappings. +* +* Configures static IP address assignments for specific MAC addresses. +* +* @param[in] ctx - Utopia context. +* @param[in] count - Number of static host entries in the dhcpMap array. +* @param[in] dhcpMap - Array of DHCPMap_t structures containing static host mappings. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +*/ int Utopia_SetDHCPServerStaticHosts (UtopiaContext *ctx, int count, DHCPMap_t *dhcpMap); + +/** +* @brief Get DHCP server static host mappings. +* +* Retrieves configured static IP address assignments. +* +* @param[in] ctx - Utopia context. +* @param[out] count - Pointer to store the number of static host entries retrieved. +* @param[out] dhcpMap - Pointer to store address of allocated DHCPMap_t array. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_GetDHCPServerStaticHosts (UtopiaContext *ctx, int *count, DHCPMap_t **dhcpMap); + +/** +* @brief Get count of DHCP server static host mappings. +* +* @param[in] ctx - Utopia context. +* @param[out] count - Pointer to store the number of static host entries. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_GetDHCPServerStaticHostsCount (UtopiaContext *ctx, int *count); + +/** +* @brief Unset/clear all DHCP server static host mappings. +* +* @param[in] ctx - Utopia context. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +*/ int Utopia_UnsetDHCPServerStaticHosts (UtopiaContext *ctx); +/** +* @brief Get ARP cache entries. +* +* Retrieves current ARP (Address Resolution Protocol) cache entries. +* +* @param[in] ctx - Utopia context. +* @param[out] count - Pointer to store the number of ARP entries retrieved. +* @param[out] out_hosts - Pointer to store address of allocated arpHost_t array. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval ERR_INSUFFICIENT_MEM for memory allocation failure. +* @retval Error code on failure. +*/ int Utopia_GetARPCacheEntries (UtopiaContext *ctx, int *count, arpHost_t **out_hosts); + +/** +* @brief Get WLAN client MAC addresses. +* +* Retrieves list of MAC addresses for currently connected WLAN clients. +* +* @param[in] ctx - Utopia context. +* @param[out] count - Pointer to store the number of WLAN clients. +* @param[out] out_maclist - Pointer to store address of allocated MAC address list. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval ERR_INSUFFICIENT_MEM for memory allocation failure. +* @retval Error code on failure. +*/ int Utopia_GetWLANClients (UtopiaContext *ctx, int *count, char **out_maclist); // Used for status and display current DHCP leases +/** +* @brief Get DHCP server LAN host information. +* +* This function used to retrieve DHCP server LAN host information that used for status and displaying current DHCP leases. +* +* @param[in] ctx - Utopia context. +* @param[out] count - Pointer to store the number of DHCP clients. +* @param[out] client_info - Pointer to store address of allocated dhcpLANHost_t array. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INSUFFICIENT_MEM for memory allocation failure. +* @retval Error code on failure. +*/ int Utopia_GetDHCPServerLANHosts (UtopiaContext *ctx, int *count, dhcpLANHost_t **client_info); + +/** +* @brief Delete a DHCP server LAN host entry by IP address. +* +* @param[in] ipaddr - IP address of the host to delete. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_SYSEVENT_CONN if unable to connect to sysevent. +* @retval Error code on failure. +*/ int Utopia_DeleteDHCPServerLANHost (char *ipaddr); @@ -771,48 +1023,446 @@ int Utopia_DeleteDHCPServerLANHost (char *ipaddr); * WAN Settings */ +/** +* @brief Set WAN settings. +* +* This function configures WAN connection. +* +* @param[in] ctx - Utopia context. +* @param[in] wan_info - Pointer to wanInfo_t structure containing WAN settings. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval ERR_INVALID_WAN_TYPE if wan_proto is invalid. +* @retval Error code on failure. +*/ int Utopia_SetWANSettings (UtopiaContext *ctx, wanInfo_t *wan_info); + +/** +* @brief Get WAN settings. +* +* Retrieves WAN connection configuration. +* +* @param[in] ctx - Utopia context. +* @param[out] wan_info - Pointer to wanInfo_t structure to store WAN settings. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval ERR_INVALID_WAN_TYPE if wan_proto is invalid. +* @retval Error code on failure. +*/ int Utopia_GetWANSettings (UtopiaContext *ctx, wanInfo_t *wan_info); #if !defined(DDNS_BROADBANDFORUM) + +/** +* @brief Set Dynamic DNS service configuration. +* +* This function configures DDNS provider, credentials, and hostname settings. +* +* @param[in] ctx - Utopia context. +* @param[in] ddns - Pointer to ddnsService_t structure containing DDNS settings. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_DDNS_TYPE if ddns provider is invalid. +* @retval Error code on failure. +*/ int Utopia_SetDDNSService (UtopiaContext *ctx, ddnsService_t *ddns); + +/** +* @brief Update Dynamic DNS service. +* +* This function triggers an update to the DDNS service. +* +* @param[in] ctx - Utopia context. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_UpdateDDNSService (UtopiaContext *ctx); + +/** +* @brief Get Dynamic DNS service configuration. +* +* Retrieves DDNS provider, credentials, and hostname settings. +* +* @param[in] ctx - Utopia context. +* @param[out] ddns - Pointer to ddnsService_t structure to store DDNS settings. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_GetDDNSService (UtopiaContext *ctx, ddnsService_t *ddns); + +/** +* @brief Get Dynamic DNS service status. +* +* Retrieves current status of DDNS update. +* +* @param[in] ctx - Utopia context. +* @param[out] ddnsStatus - Pointer to ddnsStatus_t to store DDNS status. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval ERR_SYSEVENT_CONN if unable to connect to sysevent. +* @retval Error code on failure. +*/ int Utopia_GetDDNSServiceStatus (UtopiaContext *ctx, ddnsStatus_t *ddnsStatus); #endif +/** +* @brief Set MAC address cloning. +* +* Configures WAN interface MAC address cloning. +* +* @param[in] ctx - Utopia context. +* @param[in] enable - TRUE to enable MAC cloning, FALSE to disable. +* @param[in] macaddr - MAC address to clone. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_SetMACAddressClone (UtopiaContext *ctx, boolean_t enable, char macaddr[MACADDR_SZ]); + +/** +* @brief Get MAC address cloning configuration. +* +* Retrieves MAC cloning enable status and cloned MAC address. +* +* @param[in] ctx - Utopia context. +* @param[out] enable - Pointer to store enable status. +* @param[out] macaddr - Buffer to store cloned MAC address. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +*/ int Utopia_GetMACAddressClone (UtopiaContext *ctx, boolean_t *enable, char macaddr[MACADDR_SZ]); +/** +* @brief Release WAN DHCP client lease. +* +* Sends DHCP release message to release current IP address lease. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_WANDHCPClient_Release (void); + +/** +* @brief Renew WAN DHCP client lease. +* +* Sends DHCP renew request to renew current IP address lease. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_WANDHCPClient_Renew (void); +/** +* @brief Terminate WAN connection. +* +* This function disconnects active WAN connection. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_SYSEVENT_CONN if unable to connect to sysevent. +* @retval Error code on failure. +*/ int Utopia_WANConnectionTerminate (void); + +/** +* @brief Get WAN connection information. +* +* Retrieves WAN IP address, subnet mask, default gateway, DNS servers, and lease time. +* +* @param[in] ctx - Utopia context. +* @param[out] info - Pointer to wanConnectionInfo_t structure to store connection info. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval ERR_SYSEVENT_CONN if unable to connect to sysevent. +* @retval Error code on failure. +*/ int Utopia_GetWANConnectionInfo (UtopiaContext *ctx, wanConnectionInfo_t *info); + +/** +* @brief Get WAN connection status. +* +* Retrieves WAN connection status like state, physical link, uptime, and IP address. +* +* @param[in] ctx - Utopia context. +* @param[out] wan - Pointer to wanConnectionStatus_t structure to store status. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval ERR_SYSEVENT_CONN if unable to connect to sysevent. +* @retval Error code on failure. +*/ int Utopia_GetWANConnectionStatus (UtopiaContext *ctx, wanConnectionStatus_t *wan); + +/** +* @brief Get WAN traffic information. +* +* Retrieves WAN traffic statistics including packets and bytes sent/received. +* +* @param[out] wan - Pointer to wanTrafficInfo_t structure to store traffic info. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval ERR_SYSEVENT_CONN if unable to connect to sysevent. +* @retval ERR_FILE_READ_FAILED if unable to read traffic data. +* @retval Error code on failure. +*/ int Utopia_GetWANTrafficInfo (wanTrafficInfo_t *wan); /* * Router/Bridge settings */ + +/** +* @brief Set bridge mode settings. +* +* This function configures bridge mode and related IP configuration. +* +* @param[in] ctx - Utopia context. +* @param[in] bridge_info - Pointer to bridgeInfo_t structure containing bridge settings. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval ERR_INVALID_BRIDGE_TYPE if bridge_mode is invalid. +* @retval Error code on failure. +*/ int Utopia_SetBridgeSettings (UtopiaContext *ctx, bridgeInfo_t *bridge_info); + +/** +* @brief Get bridge mode settings. +* +* Retrieves current bridge mode configuration. +* +* @param[in] ctx - Utopia context. +* @param[out] bridge_info - Pointer to bridgeInfo_t structure to store bridge settings. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval ERR_INVALID_BRIDGE_TYPE if bridge_mode is invalid. +* @retval Error code on failure. +*/ int Utopia_GetBridgeSettings (UtopiaContext *ctx, bridgeInfo_t *bridge_info); + +/** +* @brief Get bridge connection information. +* +* This function retrieves bridge connection information. +* +* @param[in] ctx - Utopia context. +* @param[out] bridge - Pointer to bridgeConnectionInfo_t structure to store connection info. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval ERR_SYSEVENT_CONN if unable to connect to sysevent. +* @retval ERR_INVALID_BRIDGE_TYPE if bridge_mode is invalid. +* @retval Error code on failure. +*/ int Utopia_GetBridgeConnectionInfo (UtopiaContext *ctx, bridgeConnectionInfo_t *bridge); /* * Route Settings */ + +/** +* @brief Set NAT (Network Address Port Translation) mode. +* +* Configures NAPT mode for routing. +* +* @param[in] ctx - Utopia context. +* @param[in] enable - NAPT mode to set. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_SetRouteNAT (UtopiaContext *ctx, napt_mode_t enable); + +/** +* @brief Get NAT (Network Address Port Translation) mode. +* +* Retrieves current NAPT mode configuration. +* +* @param[in] ctx - Utopia context. +* @param[out] enable - Pointer to store NAPT mode. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_GetRouteNAT (UtopiaContext *ctx, napt_mode_t *enable); +/** +* @brief Set RIP (Routing Information Protocol) configuration. +* +* Configures RIP settings like enable status, split horizon, interface selection, and passwords. +* +* @param[in] ctx - Utopia context. +* @param[in] rip - Pointer to routeRIP_t structure containing RIP settings. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_SetRouteRIP (UtopiaContext *ctx, routeRIP_t *rip); //CID 67860: Big parameter passed by value + +/** +* @brief Get RIP (Routing Information Protocol) configuration. +* +* Retrieves RIP settings. +* +* @param[in] ctx - Utopia context. +* @param[out] rip - Pointer to routeRIP_t structure to store RIP settings. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_GetRouteRIP (UtopiaContext *ctx, routeRIP_t *rip); +/** +* @brief Find static route by name. +* +* Searches for a static route entry by route name. +* +* @param[in] count - Number of routes in sroutes array. +* @param[in] sroutes - Array of routeStatic_t structures to search. +* @param[in] route_name - Name of the route to find. +* +* @return Index of the found route. +* @retval >=0 Index of the route in array if found. +* @retval -1 if route not found. +*/ int Utopia_FindStaticRoute (int count, routeStatic_t *sroutes, const char *route_name); + +/** +* @brief Delete static route by index. +* +* Removes a static route entry at specified index. +* +* @param[in] ctx - Utopia context. +* @param[in] index - Index of the route to delete. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval ERR_ITEM_NOT_FOUND if index is out of range. +* @retval Error code on failure. +*/ int Utopia_DeleteStaticRoute (UtopiaContext *ctx, int index); + +/** +* @brief Delete static route by name. +* +* Removes a static route entry with specified name. +* +* @param[in] ctx - Utopia context. +* @param[in] route_name - Name of the route to delete. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval ERR_ITEM_NOT_FOUND if route name does not exist. +* @retval Error code on failure. +*/ int Utopia_DeleteStaticRouteName (UtopiaContext *ctx, const char *route_name); + +/** +* @brief Add new static route. +* +* Adds a new static route entry. +* +* @param[in] ctx - Utopia context. +* @param[in] sroute - Pointer to routeStatic_t structure containing route to add. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +*/ int Utopia_AddStaticRoute (UtopiaContext *ctx, routeStatic_t *sroute); + +/** +* @brief Edit existing static route by index. +* +* Modifies a static route entry at specified index. +* +* @param[in] ctx - Utopia context. +* @param[in] index - Index of the route to edit. +* @param[in] sroute - Pointer to routeStatic_t structure containing new route data. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +*/ int Utopia_EditStaticRoute (UtopiaContext *ctx, int index, routeStatic_t *sroute); + +/** +* @brief Get count of static routes. +* +* Retrieves the number of configured static routes. +* +* @param[in] ctx - Utopia context. +* @param[out] count - Pointer to store the number of static routes. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +*/ int Utopia_GetStaticRouteCount (UtopiaContext *ctx, int *count); + +/** +* @brief Get static routes configuration. +* +* Retrieves all configured static routes. +* +* @param[in] ctx - Utopia context. +* @param[out] count - Pointer to store the number of routes retrieved. +* @param[out] out_sroute - Pointer to store address of allocated routeStatic_t array. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +*/ int Utopia_GetStaticRoutes (UtopiaContext *ctx, int *count, routeStatic_t **out_sroute); + +/** +* @brief Get static route table. +* +* Retrieves the static route table. +* +* @param[out] count - Pointer to store the number of route entries. +* @param[out] out_sroute - Pointer to store address of allocated routeStatic_t array. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval ERR_INSUFFICIENT_MEM for memory allocation failure. +* @retval Error code on failure. +*/ int Utopia_GetStaticRouteTable (int *count, routeStatic_t **out_sroute); /* @@ -823,69 +1473,773 @@ int Utopia_GetStaticRouteTable (int *count, routeStatic_t **out_sroute); * Port Mapping */ +/** +* @brief Check port trigger range for conflicts. +* +* Validates port trigger range against existing rules to detect conflicts. +* +* @param[in] ctx - Utopia context. +* @param[in] new_rule_id - Rule ID of the new/modified rule. +* @param[in] new_start - Start port of the range. +* @param[in] new_end - End port of the range. +* @param[in] new_protocol - Protocol. +* @param[in] is_trigger - TRUE if checking trigger range, FALSE if checking forward range. +* +* @return Status of the operation. +* @retval TRUE if no conflict. +* @retval FALSE if conflict detected. +*/ int Utopia_CheckPortTriggerRange(UtopiaContext *ctx, int new_rule_id, int new_start, int new_end, int new_protocol, int is_trigger); + +/** +* @brief Check port range for conflicts. +* +* Validates port range against existing rules to detect conflicts. +* +* @param[in] ctx - Utopia context. +* @param[in] new_rule_id - Rule ID of the new/modified rule. +* @param[in] new_start - Start port of the range. +* @param[in] new_end - End port of the range. +* @param[in] new_protocol - Protocol. +* @param[in] is_trigger - TRUE if checking trigger range, FALSE if checking forward range. +* +* @return Status of the operation. +* @retval TRUE if no conflict. +* @retval FALSE if conflict detected. +*/ int Utopia_CheckPortRange(UtopiaContext *ctx, int new_rule_id, int new_start, int new_end, int new_protocol, int is_trigger); +/** +* @brief Set port forwarding rules for single port mappings. +* +* Configures multiple single port forwarding rules. +* +* @param[in] ctx - Utopia context. +* @param[in] count - Number of port forwarding entries in fwdinfo array. +* @param[in] fwdinfo - Array of portFwdSingle_t structures containing forwarding rules. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_VALUE if parameters are NULL or invalid. +* @retval ERR_INVALID_IPADDR if IP address is invalid. +* @retval Error code on failure. +*/ int Utopia_SetPortForwarding (UtopiaContext *ctx, int count, portFwdSingle_t *fwdinfo); + +/** +* @brief Get port forwarding rules for single port mappings. +* +* Retrieves all configured single port forwarding rules. +* +* @param[in] ctx - Utopia context. +* @param[out] count - Pointer to store the number of port forwarding entries. +* @param[out] fwdinfo - Pointer to store address of allocated portFwdSingle_t array. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_GetPortForwarding (UtopiaContext *ctx, int *count, portFwdSingle_t **fwdinfo); + +/** +* @brief Get count of port forwarding rules. +* +* Retrieves the number of configured single port forwarding rules. +* +* @param[in] ctx - Utopia context. +* @param[out] count - Pointer to store the number of port forwarding entries. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_GetPortForwardingCount (UtopiaContext *ctx, int *count); + +/** +* @brief Find port forwarding rule by external port and protocol. +* +* Searches for a port forwarding entry matching external port and protocol. +* +* @param[in] count - Number of port mappings in portmap array. +* @param[in] portmap - Array of portFwdSingle_t structures to search. +* @param[in] external_port - External port number to find. +* @param[in] proto - Protocol. +* +* @return Index of the found port mapping. +* @retval >=0 Index in array if found. +* @retval -1 if not found. +*/ int Utopia_FindPortForwarding (int count, portFwdSingle_t *portmap, int external_port, protocol_t proto); + +/** +* @brief Add new port forwarding rule. +* +* This function adds a new single port forwarding rule. +* +* @param[in] ctx - Utopia context. +* @param[in] portmap - Pointer to portFwdSingle_t structure containing rule to add. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_VALUE if parameters are NULL or invalid. +* @retval ERR_INVALID_IP if IP address is invalid. +* @retval Error code on failure. +*/ int Utopia_AddPortForwarding (UtopiaContext *ctx, portFwdSingle_t *portmap); + +/** +* @brief Get port forwarding rule by index. +* +* Retrieves a specific port forwarding rule by array index. +* +* @param[in] ctx - Utopia context. +* @param[in] index - Index of the rule to retrieve. +* @param[out] fwdinfo - Pointer to portFwdSingle_t structure to store forwarding rule. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_ITEM_NOT_FOUND if index is out of range. +* @retval Error code on failure. +*/ int Utopia_GetPortForwardingByIndex (UtopiaContext *ctx, int index, portFwdSingle_t *fwdinfo); + +/** +* @brief Set port forwarding rule by index. +* +* Modifies a specific port forwarding rule by array index. +* +* @param[in] ctx - Utopia context. +* @param[in] index - Index of the rule to modify. +* @param[in] fwdinfo - Pointer to portFwdSingle_t structure containing new rule data. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_ITEM_NOT_FOUND if index is out of range. +* @retval Error code on failure. +*/ int Utopia_SetPortForwardingByIndex (UtopiaContext *ctx, int index, portFwdSingle_t *fwdinfo); + +/** +* @brief Delete port forwarding rule by index. +* +* Removes a port forwarding rule by array index. +* +* @param[in] ctx - Utopia context. +* @param[in] index - Index of the rule to delete. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_ITEM_NOT_FOUND if index is out of range. +* @retval Error code on failure. +*/ int Utopia_DelPortForwardingByIndex (UtopiaContext *ctx, int index); + +/** +* @brief Get port forwarding rule by rule ID. +* +* Retrieves a specific port forwarding rule by its rule ID. +* +* @param[in] ctx - Utopia context. +* @param[in,out] fwdinfo - Pointer to portFwdSingle_t structure with rule_id set on input, +* filled with rule data on output. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_VALUE if parameters are NULL or invalid. +* @retval Error code on failure. +*/ int Utopia_GetPortForwardingByRuleId (UtopiaContext *ctx, portFwdSingle_t *fwdinfo); + +/** +* @brief Set port forwarding rule by rule ID. +* +* Modifies a specific port forwarding rule by its rule ID. +* +* @param[in] ctx - Utopia context. +* @param[in] fwdinfo - Pointer to portFwdSingle_t structure with rule_id and new data. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_ITEM_NOT_FOUND if rule_id does not exist. +* @retval Error code on failure. +*/ int Utopia_SetPortForwardingByRuleId (UtopiaContext *ctx, portFwdSingle_t *fwdinfo); + +/** +* @brief Delete port forwarding rule by rule ID. +* +* Removes a port forwarding rule by its rule ID. +* +* @param[in] ctx - Utopia context. +* @param[in] rule_id - Rule ID of the forwarding rule to delete. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_ITEM_NOT_FOUND if rule_id does not exist. +* @retval Error code on failure. +*/ int Utopia_DelPortForwardingByRuleId (UtopiaContext *ctx, int rule_id); +/** +* @brief Add dynamic port mapping. +* +* Adds a dynamic port mapping entry. +* +* @param[in] portmap - Pointer to portMapDyn_t structure containing mapping to add. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +*/ int Utopia_AddDynPortMapping (portMapDyn_t *portmap); + +/** +* @brief Update dynamic port mapping. +* +* Updates an existing dynamic port mapping entry. +* +* @param[in] index - Index of the mapping to update. +* @param[in] pmap - Pointer to portMapDyn_t structure containing updated mapping data. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +*/ int Utopia_UpdateDynPortMapping (int index, portMapDyn_t *pmap); + +/** +* @brief Delete dynamic port mapping. +* +* Removes a dynamic port mapping entry. +* +* @param[in] portmap - Pointer to portMapDyn_t structure identifying mapping to delete. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +*/ int Utopia_DeleteDynPortMapping (portMapDyn_t *portmap); + +/** +* @brief Delete dynamic port mapping by index. +* +* Removes a dynamic port mapping entry by index. +* +* @param[in] index - Index of the mapping to delete. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +*/ int Utopia_DeleteDynPortMappingIndex (int index); + +/** +* @brief Invalidate all dynamic port mappings. +* +* Marks all dynamic port mappings as invalid/expired. Remove entries whose lease time expired +* this check is valid only on entries that have leasetime > 0. if leastime = 0, the entry is left +* indefinitely until it is explicitly deleted or system reboots. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_InvalidateDynPortMappings (void); + +/** +* @brief Validate dynamic port mapping. +* +* Marks a dynamic port mapping as valid/active. +* +* @param[in] index - Index of the mapping to validate. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_ValidateDynPortMapping (int index); + +/** +* @brief Get count of dynamic port mappings. +* +* Retrieves the number of dynamic port mappings. +* +* @param[out] count - Pointer to store the number of mappings. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_GetDynPortMappingCount (int *count); + +/** +* @brief Get dynamic port mapping by index. +* +* Retrieves a specific dynamic port mapping entry. +* +* @param[in] index - Index of the mapping to retrieve. +* @param[out] portmap - Pointer to portMapDyn_t structure to store mapping data. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_GetDynPortMapping (int index, portMapDyn_t *portmap); + +/** +* @brief Find dynamic port mapping. +* +* Searches for a dynamic port mapping by external host, port, and protocol. +* +* @param[in] external_host - External host IP address. +* @param[in] external_port - External port number. +* @param[in] proto - Protocol. +* @param[out] pmap - Pointer to portMapDyn_t structure to store found mapping. +* @param[out] index - Pointer to store the index of found mapping. +* +* @return Status of the operation. +* @retval UT_SUCCESS if found. +* @retval ERR_ITEM_NOT_FOUND if not found. +* @retval Error code if not found or on failure. +*/ int Utopia_FindDynPortMapping(const char *external_host, int external_port, protocol_t proto, portMapDyn_t *pmap, int *index); + +/** +* @brief Check if IGD configuration is allowed. +* +* Determines if UPnP IGD configuration is permitted. +* +* @param[in] ctx - Utopia context. +* +* @return Configuration allowed status. +* @retval 1 if IGD user configuration is allowed. +* @retval 0 if IGD configuration is not allowed. +*/ int Utopia_IGDConfigAllowed (UtopiaContext *ctx); + +/** +* @brief Check if IGD internet disable is allowed. +* +* Determines if UPnP IGD can disable internet access. +* +* @param[in] ctx - Utopia context. +* +* @return Internet disable allowed status. +* @retval 1 if IGD can disable internet. +* @retval 0 if IGD cannot disable internet. +*/ int Utopia_IGDInternetDisbleAllowed (UtopiaContext *ctx); +/** +* @brief Set port forwarding range rules. +* +* Configures multiple port forwarding rules for port ranges. +* +* @param[in] ctx - Utopia context. +* @param[in] count - Number of port forwarding range entries. +* @param[in] fwdinfo - Array of portFwdRange_t structures containing forwarding rules. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_SetPortForwardingRange (UtopiaContext *ctx, int count, portFwdRange_t *fwdinfo); + +/** +* @brief Get port forwarding range rules. +* +* @param[in] ctx - Utopia context. +* @param[out] count - Pointer to store number of entries. +* @param[out] fwdinfo - Pointer to store allocated array. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_VALUE if parameters are NULL or invalid. +* @retval ERR_INVALID_IP if IP address is invalid. +* @retval Error code on failure. +*/ int Utopia_GetPortForwardingRange (UtopiaContext *ctx, int *count, portFwdRange_t **fwdinfo); + +/** +* @brief Get count of port forwarding range rules. +* +* @param[in] ctx - Utopia context. +* @param[out] count - Pointer to store count. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_GetPortForwardingRangeCount (UtopiaContext *ctx, int *count); + +/** +* @brief Add port forwarding range rule. +* +* @param[in] ctx - Utopia context. +* @param[in] portmap - Port forwarding range rule to add. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_VALUE if parameters are NULL or invalid. +* @retval ERR_INVALID_IP if IP address is invalid. +* @retval Error code on failure. +*/ int Utopia_AddPortForwardingRange (UtopiaContext *ctx, portFwdRange_t *portmap); + +/** +* @brief Get port forwarding range rule by index. +* +* @param[in] ctx - Utopia context. +* @param[in] index - Index of rule. +* @param[out] fwdinfo - Pointer to store rule data. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_ITEM_NOT_FOUND if index is out of range. +* @retval Error code on failure. +*/ int Utopia_GetPortForwardingRangeByIndex (UtopiaContext *ctx, int index, portFwdRange_t *fwdinfo); + +/** +* @brief Set port forwarding range rule by index. +* +* @param[in] ctx - Utopia context. +* @param[in] index - Index of rule. +* @param[in] fwdinfo - Rule data to set. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_ITEM_NOT_FOUND if index is out of range. +* @retval Error code on failure. +*/ int Utopia_SetPortForwardingRangeByIndex (UtopiaContext *ctx, int index, portFwdRange_t *fwdinfo); + +/** +* @brief Delete port forwarding range rule by index. +* +* @param[in] ctx - Utopia context. +* @param[in] index - Index of rule to delete. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_ITEM_NOT_FOUND if index is out of range. +* @retval Error code on failure. +*/ int Utopia_DelPortForwardingRangeByIndex (UtopiaContext *ctx, int index); + +/** +* @brief Get port forwarding range rule by rule ID. +* +* @param[in] ctx - Utopia context. +* @param[in,out] fwdinfo - Rule ID on input, rule data on output. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_VALUE if parameters are NULL or invalid. +* @retval ERR_ITEM_NOT_FOUND if rule_id does not exist. +* @retval Error code on failure. +*/ int Utopia_GetPortForwardingRangeByRuleId (UtopiaContext *ctx, portFwdRange_t *fwdinfo); + +/** +* @brief Set port forwarding range rule by rule ID. +* +* @param[in] ctx - Utopia context. +* @param[in] fwdinfo - Rule data with rule_id. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_VALUE if parameters are NULL or invalid. +* @retval ERR_ITEM_NOT_FOUND if rule_id does not exist. +* @retval Error code on failure. +*/ int Utopia_SetPortForwardingRangeByRuleId (UtopiaContext *ctx, portFwdRange_t *fwdinfo); + +/** +* @brief Delete port forwarding range rule by rule ID. +* +* @param[in] ctx - Utopia context. +* @param[in] rule_id - Rule ID to delete. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_ITEM_NOT_FOUND if rule_id does not exist. +* @retval Error code on failure. +*/ int Utopia_DelPortForwardingRangeByRuleId (UtopiaContext *ctx, int rule_id); +/** +* @brief Set port trigger rules. +* +* @param[in] ctx - Utopia context. +* @param[in] count - Number of port trigger entries. +* @param[in] portinfo - Array of portRangeTrig_t structures. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_VALUE if parameters are NULL or invalid. +* @retval Error code on failure. +*/ int Utopia_SetPortTrigger (UtopiaContext *ctx, int count, portRangeTrig_t *portinfo); + +/** +* @brief Get port trigger rules. +* +* @param[in] ctx - Utopia context. +* @param[out] count - Pointer to store count. +* @param[out] portinfo - Pointer to store allocated array. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INSUFFICIENT_MEM for memory allocation failure. +* @retval Error code on failure. +*/ int Utopia_GetPortTrigger (UtopiaContext *ctx, int *count, portRangeTrig_t **portinfo); + +/** +* @brief Get count of port trigger rules. +* +* @param[in] ctx - Utopia context. +* @param[out] count - Pointer to store count. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_GetPortTriggerCount (UtopiaContext *ctx, int *count); + +/** +* @brief Add port trigger rule. +* +* @param[in] ctx - Utopia context. +* @param[in] portmap - Port trigger rule to add. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_VALUE if parameters are NULL or invalid. +* @retval Error code on failure. +*/ int Utopia_AddPortTrigger (UtopiaContext *ctx, portRangeTrig_t *portmap); + +/** +* @brief Get port trigger by index. +* +* @param[in] ctx - Utopia context. +* @param[in] index - Index of rule. +* @param[out] fwdinfo - Pointer to store rule data. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_ITEM_NOT_FOUND if index is out of range. +* @retval Error code on failure. +*/ int Utopia_GetPortTriggerByIndex (UtopiaContext *ctx, int index, portRangeTrig_t *fwdinfo); + +/** +* @brief Set port trigger by index. +* +* @param[in] ctx - Utopia context. +* @param[in] index - Index of rule. +* @param[in] fwdinfo - Rule data to set. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_ITEM_NOT_FOUND if index is out of range. +* @retval Error code on failure. +*/ int Utopia_SetPortTriggerByIndex (UtopiaContext *ctx, int index, portRangeTrig_t *fwdinfo); + +/** +* @brief Delete port trigger by index. +* +* @param[in] ctx - Utopia context. +* @param[in] index - Index of rule to delete. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_ITEM_NOT_FOUND if index is out of range. +* @retval Error code on failure. +*/ int Utopia_DelPortTriggerByIndex (UtopiaContext *ctx, int index); + +/** +* @brief Get port trigger by rule ID. +* +* @param[in] ctx - Utopia context. +* @param[in,out] portinfo - Rule ID on input, rule data on output. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_VALUE if parameters are NULL or invalid. +* @retval ERR_ITEM_NOT_FOUND if rule_id does not exist. +* @retval Error code on failure. +*/ int Utopia_GetPortTriggerByRuleId (UtopiaContext *ctx, portRangeTrig_t *portinfo); + +/** +* @brief Set port trigger by rule ID. +* +* @param[in] ctx - Utopia context. +* @param[in] portinfo - Rule data with rule_id. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_VALUE if parameters are NULL or invalid. +* @retval ERR_ITEM_NOT_FOUND if rule_id does not exist. +* @retval Error code on failure. +*/ int Utopia_SetPortTriggerByRuleId (UtopiaContext *ctx, portRangeTrig_t *portinfo); + +/** +* @brief Delete port trigger by rule ID. +* +* @param[in] ctx - Utopia context. +* @param[in] trigger_id - Trigger ID to delete. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_ITEM_NOT_FOUND if rule_id does not exist. +* @retval Error code on failure. +*/ int Utopia_DelPortTriggerByRuleId (UtopiaContext *ctx, int trigger_id); +/** +* @brief Set DMZ settings. +* +* Configures Demilitarized Zone settings like enable status and destination IP/MAC. +* +* @param[in] ctx - Utopia context. +* @param[in] dmz - Pointer to dmz_t structure containing DMZ settings. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +*/ int Utopia_SetDMZSettings (UtopiaContext *ctx, dmz_t *dmz); + +/** +* @brief Get DMZ settings. +* +* @param[in] ctx - Utopia context. +* @param[out] out_dmz - Pointer to dmz_t structure to store DMZ settings. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +*/ int Utopia_GetDMZSettings (UtopiaContext *ctx, dmz_t *out_dmz); +/** +* @brief Add Internet Access Policy. +* +* @param[in] ctx - Utopia context. +* @param[in] iap - Pointer to iap_entry_t structure containing policy. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +*/ int Utopia_AddInternetAccessPolicy (UtopiaContext *ctx, iap_entry_t *iap); + +/** +* @brief Edit Internet Access Policy. +* +* @param[in] ctx - Utopia context. +* @param[in] index - Index of policy to edit. +* @param[in] iap - Pointer to iap_entry_t structure with new policy data. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +*/ int Utopia_EditInternetAccessPolicy (UtopiaContext *ctx, int index, iap_entry_t *iap); + +/** +* @brief Add LAN hosts to Internet Access Policy. +* +* @param[in] ctx - Utopia context. +* @param[in] policyname - Name of policy. +* @param[in] lanhosts - Pointer to lanHosts_t structure containing LAN hosts. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_AddInternetAccessPolicyLanHosts (UtopiaContext *ctx, const char *policyname, lanHosts_t *lanhosts); + +/** +* @brief Delete Internet Access Policy. +* +* @param[in] ctx - Utopia context. +* @param[in] policyname - Name of policy to delete. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval ERR_INVALID_VALUE if policy does not exist. +* @retval Error code on failure. +*/ int Utopia_DeleteInternetAccessPolicy (UtopiaContext *ctx, const char *policyname); + +/** +* @brief Get Internet Access Policies. +* +* @param[in] ctx - Utopia context. +* @param[out] out_count - Pointer to store count. +* @param[out] out_iap - Pointer to store allocated array. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval ERR_INSUFFICIENT_MEM for memory allocation failure. +* @retval Error code on failure. +*/ int Utopia_GetInternetAccessPolicy (UtopiaContext *ctx, int *out_count, iap_entry_t **out_iap); + +/** +* @brief Find Internet Access Policy by name. +* +* @param[in] ctx - Utopia context. +* @param[in] policyname - Policy name to find. +* @param[out] out_iap - Pointer to store policy data. +* @param[out] out_index - Pointer to store policy index. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval ERR_ITEM_NOT_FOUND if policy not found. +* @retval Error code on failure. +*/ int Utopia_FindInternetAccessPolicy (UtopiaContext *ctx, const char *policyname, iap_entry_t *out_iap, int *out_index); + +/** +* @brief Free Internet Access Policy memory. +* +* @param[in] iap - Pointer to iap_entry_t to free. +* +* @return None. +*/ void Utopia_FreeInternetAccessPolicy (iap_entry_t *iap); -/* - * Returns a null terminated array of strings with network - * service names like ftp, telnet, dns, etc - */ + +/** +* @brief Get network services list. +* +* Returns a null terminated array of strings with network service names like ftp, telnet, dns, etc. +* +* @param[out] out_list - Pointer to receive service list. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_GetNetworkServicesList (const char **out_list); typedef struct firewall { @@ -917,7 +2271,30 @@ typedef struct firewall { boolean_t wan_ping_enable_v6; } firewall_t; +/** +* @brief Set firewall settings. +* +* Configures general firewall settings like SPI protection, packet filtering options. +* +* @param[in] ctx - Utopia context. +* @param[in] fw - Firewall settings structure. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_SetFirewallSettings (UtopiaContext *ctx, firewall_t fw); + +/** +* @brief Get firewall settings. +* +* @param[in] ctx - Utopia context. +* @param[out] fw - Pointer to firewall_t structure to store settings. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_GetFirewallSettings (UtopiaContext *ctx, firewall_t *fw); typedef struct ipv6Prefix { @@ -974,7 +2351,34 @@ typedef struct ipv6Info { int ra_provisioning_enable ; /* Whether to listen to RA on the WAN side */ } ipv6Info_t ; +/** +* @brief Set IPv6 settings. +* +* Configures IPv6 settings such as tunnel modes (6rd, 6to4, AICCU, HE), DHCPv6 client/server. +* +* @param[in] ctx - Utopia context. +* @param[in] ipv6_info - Pointer to ipv6Info_t structure containing IPv6 settings. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +*/ int Utopia_SetIPv6Settings (UtopiaContext *ctx, ipv6Info_t *ipv6_info); + +/** +* @brief Get IPv6 settings. +* +* Retrieves current IPv6 configuration and status information such as connection state. +* +* @param[in] ctx - Utopia context. +* @param[out] ipv6_info - Pointer to ipv6Info_t structure to store IPv6 settings. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +*/ int Utopia_GetIPv6Settings (UtopiaContext *ctx, ipv6Info_t *ipv6_info); /* @@ -1001,59 +2405,436 @@ typedef struct { boolean_t allow_userconfig; boolean_t allow_wandisable; } igdconf_t; - + +/** +* @brief Restore factory defaults. +* +* Resets the device configuration to factory default settings. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_RestoreFactoryDefaults (void); + +/** +* @brief Restore configuration from file. +* +* Restores device configuration from a previously saved backup file. +* +* @param[in] config_fname - Path to configuration backup file. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval ERR_INSUFFICIENT_MEM for memory allocation failure. +* @retval ERR_INVALID_SYSCFG_FILE if the config file is invalid. +* @retval Error code on failure. +*/ int Utopia_RestoreConfiguration (char *config_fname); + +/** +* @brief Backup configuration to file. +* +* Saves current device configuration to a backup file. +* +* @param[in] out_config_fname - Path where backup file will be created. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval ERR_INSUFFICIENT_MEM for memory allocation failure. +* @retval ERR_FILE_WRITE_FAILED if unable to write to file. +* @retval Error code on failure. +*/ int Utopia_BackupConfiguration (char *out_config_fname); + +/** +* @brief Perform firmware upgrade. +* +* Upgrades device firmware from specified firmware file. +* +* @param[in] ctx - Utopia context. +* @param[in] firmware_file - Path to firmware image file. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval ERR_FW_UPGRADE_LOCK_CONFLICT if another upgrade is in progress. +* @retval ERR_FILE_WRITE_FAILED if unable to read firmware file. +* @retval Error code on failure. +*/ int Utopia_FirmwareUpgrade (UtopiaContext *ctx, char *firmware_file); + +/** +* @brief Check if firmware upgrade is allowed. +* +* Validates if firmware upgrade is permitted based on current configuration and access port. +* +* @param[in] ctx - Utopia context. +* @param[in] http_port - HTTP port being used for upgrade request. +* +* @return Status of the operation. +* @retval 1 if upgrade is allowed. +* @retval 0 if upgrade is not allowed. +*/ int Utopia_IsFirmwareUpgradeAllowed (UtopiaContext *ctx, int http_port); + +/** +* @brief Acquire firmware upgrade lock. +* +* Obtains exclusive lock for firmware upgrade operation to prevent concurrent upgrades. +* +* @param[out] lock_fd - Pointer to store lock file descriptor. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval ERR_FILE_NOT_FOUND if failed to open file. +* @retval ERR_FW_UPGRADE_LOCK_CONFLICT if lock is already held. +* @retval Error code on failure. +*/ int Utopia_AcquireFirmwareUpgradeLock (int *lock_fd); + +/** +* @brief Release firmware upgrade lock. +* +* Releases previously acquired firmware upgrade lock. +* +* @param[in] lock_fd - Lock file descriptor to release. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval ERR_FW_UPGRADE_LOCK_CONFLICT if lock is not held. +* @retval Error code on failure. +*/ int Utopia_ReleaseFirmwareUpgradeLock (int lock_fd); + +/** +* @brief Check if system changes are allowed. +* +* Determines if configuration changes are permitted in current system state. +* +* @return Status of the operation. +* @retval 1 if system changes are allowed. +* @retval 0 if system changes are not allowed. +*/ int Utopia_SystemChangesAllowed (void); + +/** +* @brief Reboot the device. +* +* Initiates a system reboot. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_REBOOT_FAILED on failure. +*/ int Utopia_Reboot (void); +/** +* @brief Set WebUI admin password. +* +* Sets or changes the administrator password for WebUI access. +* +* @param[in] ctx - Utopia context. +* @param[in] username - Admin username. +* @param[in] cleartext_password - New password in cleartext. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval ERR_FILE_NOT_FOUND if file failed to open. +* @retval ERR_INVALID_VALUE if username does not exist. +* @retval Error code on failure. +*/ int Utopia_SetWebUIAdminPasswd (UtopiaContext *ctx, char *username, char *cleartext_password); + +/** +* @brief Check if Admin configuration is default. +* +* Determines if the current Admin configuration is still set to the factory default value. +* +* @param[in] ctx - Utopia context. +* @param[out] is_admin_default - Pointer to boolean indicating if password is default. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +*/ int Utopia_IsAdminDefault (UtopiaContext *ctx, boolean_t *is_admin_default); + +/** +* @brief Set WebUI settings. +* +* Configures WebUI access settings such as HTTP/HTTPS access, WiFi management, +* WAN access controls, and source IP restrictions. +* +* @param[in] ctx - Utopia context. +* @param[in] ui - Pointer to webui_t structure containing WebUI settings. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +*/ int Utopia_SetWebUISettings (UtopiaContext *ctx, webui_t *ui); + +/** +* @brief Get WebUI settings. +* +* @param[in] ctx - Utopia context. +* @param[out] ui - Pointer to webui_t structure to store WebUI settings. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +*/ int Utopia_GetWebUISettings (UtopiaContext *ctx, webui_t *ui); +/** +* @brief Set IGD (Internet Gateway Device) settings. +* +* Configures UPnP IGD settings like enable status and user configuration permissions. +* +* @param[in] ctx - Utopia context. +* @param[in] igd - Pointer to igdconf_t structure containing IGD settings. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +*/ int Utopia_SetIGDSettings (UtopiaContext *ctx, igdconf_t *igd); + +/** +* @brief Get IGD (Internet Gateway Device) settings. +* +* @param[in] ctx - Utopia context. +* @param[out] igd - Pointer to igdconf_t structure to store IGD settings. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +*/ int Utopia_GetIGDSettings (UtopiaContext *ctx, igdconf_t *igd); /* * Logging and Diagnostics */ -/* - * Notes: caller need to free log array - */ +/** +* @brief Get incoming traffic log entries. +* +* @param[in] ctx - Utopia context. +* @param[out] count - Pointer to store count of log entries. +* @param[out] ilog - Pointer to receive allocated log array. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +* +* @note caller need to free log array. +*/ int Utopia_GetIncomingTrafficLog (UtopiaContext *ctx, int *count, logentry_t **ilog); -/* - * Notes: caller need to free log array - */ +/** +* @brief Get outgoing traffic log entries. +* +* @param[in] ctx - Utopia context. +* @param[out] count - Pointer to store count of log entries. +* @param[out] olog - Pointer to receive allocated log array. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +* +* @note caller need to free log array. +*/ int Utopia_GetOutgoingTrafficLog (UtopiaContext *ctx, int *count, logentry_t **olog); -/* - * Notes: caller need to free log array - */ +/** +* @brief Get security log entries. +* +* @param[in] ctx - Utopia context. +* @param[out] count - Pointer to store count of log entries. +* @param[out] slog - Pointer to receive allocated log array. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_GetSecurityLog (UtopiaContext *ctx, int *count, logentry_t **slog); +/** +* @brief Get DHCP client log. +* +* @param[in] ctx - Utopia context. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_GetDHCPClientLog (UtopiaContext *ctx); +/** +* @brief Set log settings. +* +* Configures logging enable status and log viewer path. +* +* @param[in] ctx - Utopia context. +* @param[in] log_enabled - Boolean to enable/disable logging. +* @param[in] log_viewer - Path to log viewer application. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_SetLogSettings (UtopiaContext *ctx, boolean_t log_enabled, char *log_viewer); + +/** +* @brief Get log settings. +* +* @param[in] ctx - Utopia context. +* @param[out] log_enabled - Pointer to store logging enable status. +* @param[out] log_viewer - Buffer to store log viewer path. +* @param[in] sz - Size of log_viewer buffer. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_GetLogSettings (UtopiaContext *ctx, boolean_t *log_enabled, char *log_viewer, int sz); +/** +* @brief Start diagnostic ping test. +* +* Initiates a ping test to specified destination with given packet size and count. +* +* @param[in] dest - Destination IP address or hostname. +* @param[in] packet_size - Size of ping packets in bytes. +* @param[in] num_ping - Number of ping packets to send. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +*/ int Utopia_DiagPingTestStart (char *dest, int packet_size, int num_ping); + +/** +* @brief Stop diagnostic ping test. +* +* Terminates currently running ping test. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_DiagPingTestStop (void); + +/** +* @brief Check if diagnostic ping test is running. +* +* @return Test status. +* @retval Non-zero if test is running. +* @retval 0 if test is not running. +*/ int Utopia_DiagPingTestIsRunning (void); + +/** +* @brief Start diagnostic traceroute test. +* +* Initiates a traceroute test to specified destination. +* +* @param[in] dest - Destination IP address or hostname. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval ERR_FILE_NOT_FOUND if failed to open +* @retval Error code on failure. +*/ int Utopia_DiagTracerouteTestStart (char *dest); + +/** +* @brief Stop diagnostic traceroute test. +* +* Terminates currently running traceroute test. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_DiagTracerouteTestStop (void); + +/** +* @brief Check if diagnostic traceroute test is running. +* +* @return Test status. +* @retval Non-zero if test is running. +* @retval 0 if test is not running. +*/ int Utopia_DiagTracerouteTestIsRunning (void); +/** +* @brief Execute diagnostic ping test. +* +* Performs a ping test to destination and returns results. +* +* @param[in] ctx - Utopia context. +* @param[in] dest - Destination IP address or hostname. +* @param[in] packet_size - Size of ping packets in bytes. +* @param[in] num_ping - Number of ping packets to send. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int diagPingTest (UtopiaContext *ctx, String dest, int packet_size, int num_ping); -int diagTraceroute (UtopiaContext *ctx, String dest, char **results_buffer); +/** +* @brief Execute diagnostic traceroute test. +* +* Performs a traceroute test to destination and returns results. +* +* @param[in] ctx - Utopia context. +* @param[in] dest - Destination IP address or hostname. +* @param[out] results_buffer - Pointer to buffer for storing results. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ +int diagTraceroute (UtopiaContext *ctx, String dest, char **results_buffer); + +/** +* @brief Connect PPP session. +* +* Initiates a PPP (Point-to-Point Protocol) connection for WAN. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_SYSEVENT_CONN if unable to set sysevent for connection. +* @retval Error code on failure. +*/ int Utopia_PPPConnect (void); + +/** +* @brief Disconnect PPP session. +* +* Terminates the active PPP connection. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_SYSEVENT_CONN if unable to set sysevent for disconnection. +* @retval Error code on failure. +*/ int Utopia_PPPDisconnect (void); @@ -1080,7 +2861,7 @@ typedef struct byoi { byoi_wanProto_t wan_proto; byoi_wan_ppp_t ppp; hsd_type_t byoi_mode; - boolean_t byoi_bridge_mode; + boolean_t byoi_bridge_mode; }byoi_t; int Utopia_Get_BYOI(UtopiaContext *ctx, byoi_t *byoi); int Utopia_Set_BYOI(UtopiaContext *ctx, byoi_t *byoi); @@ -1091,7 +2872,7 @@ typedef enum hsd_type { PRIMARY_PROVIDER_HSD, PRIMARY_PROVIDER_RESTRICTED, USER_SELECTABLE -} hsd_type_t; +} hsd_type_t; typedef enum { @@ -1100,12 +2881,79 @@ typedef enum { NONE } hsdStatus_t; +/** +* @brief Get BYOI allowed status. +* +* Determines if BYOI mode is permitted on the device. +* +* @param[in] ctx - Utopia context. +* @param[out] value - Pointer to store BYOI allowed status. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval ERR_SYSEVENT_CONN if unable to get sysevent value. +* @retval Error code on failure. +*/ int Utopia_Get_BYOI_allowed(UtopiaContext *ctx, int *value); -int Utopia_Get_BYOI_Current_Provider(UtopiaContext *ctx, hsdStatus_t *hsdStatus); + +/** +* @brief Get current BYOI provider status. +* +* Returns the currently active High-Speed Data provider. +* +* @param[in] ctx - Utopia context. +* @param[out] hsdStatus - Pointer to store current provider status. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval ERR_UTCTX_INIT if Utopia context is not initialized. +* @retval ERR_SYSEVENT_CONN if unable to get sysevent value. +* @retval Error code on failure. +*/ +int Utopia_Get_BYOI_Current_Provider(UtopiaContext *ctx, hsdStatus_t *hsdStatus); + +/** +* @brief Set desired BYOI provider. +* +* Configures the desired High-Speed Data provider selection. +* +* @param[in] ctx - Utopia context. +* @param[in] hsdStatus - Desired provider status to set. +* +* @return Status of the operation. +* @retval UT_SUCCESS on success. +* @retval ERR_UTCTX_INIT if Utopia context is not initialized. +* @retval ERR_SYSEVENT_CONN if unable to set sysevent value. +* @retval Error code on failure. +*/ int Utopia_Set_BYOI_Desired_Provider(UtopiaContext *ctx, hsdStatus_t hsdStatus); -/* Web Timeout Config value in minutes*/ +/** +* @brief Get web session timeout value. +* +* Retrieves the inactivity timeout for WebUI sessions in minutes. +* +* @param[in] ctx - Utopia context. +* @param[out] count - Pointer to store timeout value in minutes. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_GetWebTimeout(UtopiaContext *ctx, int *count); + +/** +* @brief Set web session timeout value. +* +* Configures the inactivity timeout for WebUI sessions in minutes. +* +* @param[in] ctx - Utopia context. +* @param[in] count - Timeout value in minutes. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_SetWebTimeout(UtopiaContext *ctx, int count); /*typedef enum { @@ -1119,41 +2967,433 @@ typedef struct http_user { //userType_t usertype; } http_user_t; +/** +* @brief Get HTTP user credentials. +* +* Retrieves home user account credentials for HTTP access. +* +* @param[in] ctx - Utopia context. +* @param[out] httpuser - Pointer to http_user_t structure to store user credentials. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_UTCTX_INIT if Utopia context is not initialized. +* @retval Error code on failure. +*/ int Utopia_Get_Http_User(UtopiaContext *ctx, http_user_t *httpuser); + +/** +* @brief Set HTTP user credentials. +* +* Configures home user account credentials for HTTP access. +* +* @param[in] ctx - Utopia context. +* @param[in] httpuser - Pointer to http_user_t structure containing user credentials. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_Set_Http_User(UtopiaContext *ctx, http_user_t *httpuser); + +/** +* @brief Get HTTP admin credentials. +* +* Retrieves administrator account credentials for HTTP access. +* +* @param[in] ctx - Utopia context. +* @param[out] httpuser - Pointer to http_user_t structure to store admin credentials. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_UTCTX_INIT if Utopia context is not initialized. +* @retval Error code on failure. +*/ int Utopia_Get_Http_Admin(UtopiaContext *ctx, http_user_t *httpuser); + +/** +* @brief Set HTTP admin credentials. +* +* Configures administrator account credentials for HTTP access. +* +* @param[in] ctx - Utopia context. +* @param[in] httpuser - Pointer to http_user_t structure containing admin credentials. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_Set_Http_Admin(UtopiaContext *ctx, http_user_t *httpuser); -int Utopia_Set_Prov_Code(UtopiaContext *ctx, char *val) ; -int Utopia_Get_Prov_Code(UtopiaContext *ctx, char *val) ; +/** +* @brief Set provisioning code. +* +* Stores the device provisioning code. +* +* @param[in] ctx - Utopia context. +* @param[in] val - Provisioning code string. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ +int Utopia_Set_Prov_Code(UtopiaContext *ctx, char *val); + +/** +* @brief Get provisioning code. +* +* Retrieves the device provisioning code. +* +* @param[in] ctx - Utopia context. +* @param[out] val - Buffer to store provisioning code. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +*/ +int Utopia_Get_Prov_Code(UtopiaContext *ctx, char *val); + +/** +* @brief Get first use date. +* +* Retrieves the date when the device was first used. +* +* @param[in] ctx - Utopia context. +* @param[out] val - Buffer to store first use date. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +*/ int Utopia_Get_First_Use_Date(UtopiaContext *ctx, char *val); /* NTP Functions */ +/** +* @brief Set NTP server address. +* +* Configures an NTP (Network Time Protocol) server at specified index. +* +* @param[in] ctx - Utopia context. +* @param[in] server - NTP server address (hostname or IP). +* @param[in] index - Server index. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_UTCTX_INIT if Utopia context is not initialized. +* @retval Error code on failure. +*/ int Utopia_Set_DeviceTime_NTPServer(UtopiaContext *ctx, char *server, int index); + +/** +* @brief Get NTP server address. +* +* Retrieves the NTP server configured at specified index. +* +* @param[in] ctx - Utopia context. +* @param[out] server - Buffer to store NTP server address. +* @param[in] index - Server index. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_UTCTX_INIT if Utopia context is not initialized. +* @retval ERR_SYSCFG_FAILED if unable to get syscfg value. +* @retval Error code on failure. +*/ int Utopia_Get_DeviceTime_NTPServer(UtopiaContext *ctx, char *server,int index); + +/** +* @brief Set local timezone. +* +* Configures the device timezone setting. +* +* @param[in] ctx - Utopia context. +* @param[in] tz - Timezone string. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_UTCTX_INIT if Utopia context is not initialized. +* @retval Error code on failure. +*/ int Utopia_Set_DeviceTime_LocalTZ(UtopiaContext *ctx, char *tz); + +/** +* @brief Get local timezone. +* +* Retrieves the device timezone setting. +* +* @param[in] ctx - Utopia context. +* @param[out] tz - Buffer to store timezone string. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_UTCTX_INIT if Utopia context is not initialized. +* @retval ERR_SYSCFG_FAILED if unable to get syscfg value. +* @retval Error code on failure. +*/ int Utopia_Get_DeviceTime_LocalTZ(UtopiaContext *ctx, char *tz); + +/** +* @brief Set device time enable status. +* +* Enables or disables automatic time synchronization via NTP. +* +* @param[in] ctx - Utopia context. +* @param[in] enable - Enable status (1=enable, 0=disable). +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_UTCTX_INIT if Utopia context is not initialized. +* @retval Error code on failure. +*/ int Utopia_Set_DeviceTime_Enable(UtopiaContext *ctx, unsigned char enable); + +/** +* @brief Get device time enable status. +* +* Retrieves whether automatic time synchronization is enabled. +* +* @param[in] ctx - Utopia context. +* +* @return Enable status. +* @retval 1 if enabled. +* @retval 0 if disabled. +*/ unsigned char Utopia_Get_DeviceTime_Enable(UtopiaContext *ctx); + +/** +* @brief Get device time synchronization status. +* +* Checks if device time is currently synchronized with NTP server. +* +* @param[in] ctx - Utopia context. +* +* @return Synchronization status. +* @retval Non-zero if synchronized. +* @retval 0 if not synchronized. +*/ int Utopia_Get_DeviceTime_Status(UtopiaContext *ctx); + +/** +* @brief Set daylight saving time enable status. +* +* Enables or disables automatic daylight saving time adjustment. +* +* @param[in] ctx - Utopia context. +* @param[in] enable - Enable status (1=enable, 0=disable). +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_UTCTX_INIT if Utopia context is not initialized. +* @retval Error code on failure. +*/ int Utopia_Set_DeviceTime_DaylightEnable(UtopiaContext *ctx, unsigned char enable); + +/** +* @brief Get daylight saving time enable status. +* +* Retrieves whether automatic daylight saving time adjustment is enabled. +* +* @param[in] ctx - Utopia context. +* +* @return Enable status. +* @retval 1 if enabled. +* @retval 0 if disabled. +*/ unsigned char Utopia_Get_DeviceTime_DaylightEnable(UtopiaContext *ctx); + +/** +* @brief Get daylight saving time offset. +* +* Retrieves the DST offset in minutes. +* +* @param[in] ctx - Utopia context. +* @param[out] count - Pointer to store DST offset in minutes. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_Get_DeviceTime_DaylightOffset(UtopiaContext *ctx, int *count); + +/** +* @brief Set daylight saving time offset. +* +* Configures the DST offset in minutes. +* +* @param[in] ctx - Utopia context. +* @param[in] count - DST offset in minutes. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_Set_DeviceTime_DaylightOffset(UtopiaContext *ctx, int count); +/** +* @brief Get MAC address of MG WAN interface. +* +* Retrieves the MAC address of the Management WAN interface. +* +* @param[in] ctx - Utopia context. +* @param[out] val - Buffer to store MAC address. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_ARGS if parameters are NULL or invalid. +* @retval Error code on failure. +*/ int Utopia_Get_Mac_MgWan(UtopiaContext *ctx, char *val); +/** +* @brief Get Ethernet associated devices. +* +* Retrieves MAC addresses of devices associated with specified Ethernet port. +* +* @param[in] unitId - Unit identifier. +* @param[in] portId - Port identifier. +* @param[out] macAddrList - Buffer to store MAC address list. +* @param[out] numMacAddr - Pointer to store number of MAC addresses. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_FILE_OPEN_FAIL if failed to open file. +* @retval ERR_FILE_CLOSE_FAIL if failed to close file +* @retval Error code on failure. +*/ int Utopia_GetEthAssocDevices(int unitId, int portId, unsigned char *macAddrList,int *numMacAddr); +/** +* @brief Get LAN management count. +* +* Retrieves the count of LAN management instances. +* +* @param[in] ctx - Utopia context. +* @param[out] val - Pointer to store count. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_GetLanMngmCount(UtopiaContext *ctx, int *val); + +/** +* @brief Set LAN management instance number. +* +* Configures the LAN management instance number. +* +* @param[in] ctx - Utopia context. +* @param[in] val - Instance number value. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_VALUE if the value is invalid. +* @retval Error code on failure. +*/ int Utopia_SetLanMngmInsNum(UtopiaContext *ctx, unsigned long int val); + +/** +* @brief Get LAN management instance number. +* +* Retrieves the LAN management instance number. +* +* @param[in] ctx - Utopia context. +* @param[out] val - Pointer to store instance number. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_GetLanMngmInsNum(UtopiaContext *ctx, unsigned long int *val); + +/** +* @brief Get LAN management alias. +* +* Retrieves the alias for LAN management. +* +* @param[in] ctx - Utopia context. +* @param[out] buf - Buffer to store alias. +* @param[in] b_len - Buffer length. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_VALUE if the value is invalid. +* @retval Error code on failure. +*/ int Utopia_GetLanMngmAlias(UtopiaContext *ctx, char *buf, size_t b_len ); + +/** +* @brief Set LAN management alias. +* +* Configures the alias for LAN management. +* +* @param[in] ctx - Utopia context. +* @param[in] val - Alias string. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_VALUE if the value is invalid. +* @retval Error code on failure. +*/ int Utopia_SetLanMngmAlias(UtopiaContext *ctx, const char *val); //int Utopia_GetLanMngmLanMode(UtopiaContext *ctx, lanMngm_LanMode_t *LanMode); //int Utopia_SetLanMngmLanMode(UtopiaContext *ctx, lanMngm_LanMode_t LanMode); + +/** +* @brief Get LAN networks allow status. +* +* Retrieves whether LAN networks are allowed. +* +* @param[in] ctx - Utopia context. +* @param[out] allow - Pointer to store allow status. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_GetLanMngmLanNetworksAllow(UtopiaContext *ctx, int* allow); + +/** +* @brief Set LAN networks allow status. +* +* Configures whether LAN networks are allowed. +* +* @param[in] ctx - Utopia context. +* @param[in] allow - Allow status. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_VALUE if the value is invalid. +* @retval Error code on failure. +*/ int Utopia_SetLanMngmLanNetworksAllow(UtopiaContext *ctx, int allow); + +/** +* @brief Get LAN NAPT mode. +* +* Retrieves the Network Address Port Translation mode for LAN. +* +* @param[in] ctx - Utopia context. +* @param[out] enable - Pointer to store NAPT mode. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_GetLanMngmLanNapt(UtopiaContext *ctx, napt_mode_t *enable); + +/** +* @brief Set LAN NAPT mode. +* +* Configures the Network Address Port Translation mode for LAN. +* +* @param[in] ctx - Utopia context. +* @param[in] enable - NAPT mode to set. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_SetLanMngmLanNapt(UtopiaContext *ctx, napt_mode_t enable); #define DNS_CLIENT_NAMESERVER_CNT 10 @@ -1162,11 +3402,78 @@ typedef struct dns_client{ char dns_server[DNS_CLIENT_NAMESERVER_CNT][IPADDR_SZ]; }DNS_Client_t; +/** +* @brief Set DNS enable status. +* +* This function enables or disables DNS functionality. +* +* @param[in] ctx - Utopia context. +* @param[in] enable - Enable status. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_VALUE if invalid value. +* @retval Error code on failure. +*/ int Utopia_SetDNSEnable(UtopiaContext *ctx, boolean_t enable); + +/** +* @brief Get DNS enable status. +* +* Retrieves whether DNS functionality is enabled. +* +* @param[in] ctx - Utopia context. +* @param[out] enable - Pointer to store enable status. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_GetDNSEnable(UtopiaContext *ctx, boolean_t* enable); + +/** +* @brief Get DNS servers. +* +* Retrieves configured DNS server addresses. +* +* @param[in] ctx - Utopia context. +* @param[out] dns - Pointer to DNS_Client_t structure to store DNS servers. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_INVALID_VALUE if invalid value. +* @retval ERR_FILE_NOT_FOUND if failed to open file. +* @retval Error code on failure. +*/ int Utopia_GetDNSServer(UtopiaContext *ctx, DNS_Client_t * dns); +/** +* @brief Configure ephemeral port forwarding rule. +* +* Adds or removes an ephemeral (temporary) port forwarding rule via IP tables. +* +* @param[in] pmap - Pointer to portMapDyn_t structure containing mapping details. +* @param[in] isCallForAdd - Boolean indicating add (TRUE) or remove (FALSE) operation. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval ERR_SYSEVENT_CONN if unable to set sysevent value. +* @retval ERR_INVALID_VALUE if invalid value. +* @retval Error code on failure. +*/ int Utopia_IPRule_ephemeral_port_forwarding( portMapDyn_t *pmap, boolean_t isCallForAdd ); + +/** +* @brief Check if IP address is private. +* +* Validates whether the specified IP address is in a private address range. +* +* @param[in] ip_to_check - IP address string to check. +* +* @return Check result. +* @retval Non-zero if IP is private. +* @retval 0 if IP is public. +*/ int Utopia_privateIpCheck(char *ip_to_check); #if defined(DDNS_BROADBANDFORUM) @@ -1183,13 +3490,104 @@ typedef struct DynamicDnsClient boolean_t Enable; }DynamicDnsClient_t; +/** +* @brief Get dynamic DNS client instance number by index. +* +* Retrieves the instance number for a dynamic DNS client at specified index. +* +* @param[in] ctx - Utopia context. +* @param[in] uIndex - Client index. +* @param[out] ins - Pointer to store instance number. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_GetDynamicDnsClientInsNumByIndex(UtopiaContext *ctx, unsigned long uIndex, int *ins); + +/** +* @brief Get number of dynamic DNS clients. +* +* Retrieves the count of configured dynamic DNS clients. +* +* @param[in] ctx - Utopia context. +* @param[out] num - Pointer to store client count. +* +* @return Status of the operation. +* @retval SUCCESS on success. +* @retval Error code on failure. +*/ int Utopia_GetNumberOfDynamicDnsClient(UtopiaContext *ctx, int *num); + +/** +* @brief Get dynamic DNS client by index. +* +* Retrieves dynamic DNS client configuration at specified index. +* +* @param[in] ctx - Utopia context. +* @param[in] ulIndex - Client index. +* @param[out] DynamicDnsClient - Pointer to DynamicDnsClient_t structure to store configuration. +* +* @return Status of the operation. +* @retval 0 on success. +*/ int Utopia_GetDynamicDnsClientByIndex(UtopiaContext *ctx, unsigned long ulIndex, DynamicDnsClient_t *DynamicDnsClient); + +/** +* @brief Set dynamic DNS client by index. +* +* Updates dynamic DNS client configuration at specified index. +* +* @param[in] ctx - Utopia context. +* @param[in] ulIndex - Client index. +* @param[in] DynamicDnsClient - Pointer to DynamicDnsClient_t structure containing new configuration. +* +* @return Status of the operation. +* @retval 0 on success. +*/ int Utopia_SetDynamicDnsClientByIndex(UtopiaContext *ctx, unsigned long ulIndex, const DynamicDnsClient_t *DynamicDnsClient); + +/** +* @brief Set dynamic DNS client instance and alias by index. +* +* Configures instance number and alias for dynamic DNS client at specified index. +* +* @param[in] ctx - Utopia context. +* @param[in] ulIndex - Client index. +* @param[in] ins - Instance number. +* @param[in] alias - Alias string. +* +* @return Status of the operation. +* @retval 0 on success. +*/ int Utopia_SetDynamicDnsClientInsAndAliasByIndex(UtopiaContext *ctx, unsigned long ulIndex, unsigned long ins, const char *alias); + +/** +* @brief Add dynamic DNS client. +* +* Adds a new dynamic DNS client configuration. +* +* @param[in] ctx - Utopia context. +* @param[in] DynamicDnsClient - Pointer to DynamicDnsClient_t structure containing client configuration. +* +* @return Status of the operation. +* @retval 0 on success. +*/ int Utopia_AddDynamicDnsClient(UtopiaContext *ctx, const DynamicDnsClient_t *DynamicDnsClient); + +/** +* @brief Delete dynamic DNS client. +* +* Removes dynamic DNS client by instance number. +* +* @param[in] ctx - Utopia context. +* @param[in] ins - Instance number of client to delete. +* +* @return Status of the operation. +* @retval 0 on success. +* @retval -1 if the client with the specified instance number is not found. +*/ int Utopia_DelDynamicDnsClient(UtopiaContext *ctx, unsigned long ins); #endif -#endif // _UTAPI_H_ +#endif // _UTAPI_H_ \ No newline at end of file diff --git a/source/include/utctx/utctx.h b/source/include/utctx/utctx.h index 7d3928e6..c5a460b1 100644 --- a/source/include/utctx/utctx.h +++ b/source/include/utctx/utctx.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -63,24 +63,30 @@ typedef struct _UtopiaContext UtopiaRWLock rwLock; } UtopiaContext; -/* - * Procedure : Utopia_Init - * Purpose : Initialize Utopia context - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Initialize Utopia context. +* +* Initializes the Utopia context by clearing event flags, handles, and transaction list. +* Initializes the read/write lock and the syscfg system. +* +* @param[in,out] pUtopiaCtx - UtopiaContext pointer. +* +* @return The status of the operation. +* @retval 1 on success. +* @retval 0 on error. +*/ extern int Utopia_Init(UtopiaContext* pUtopiaCtx); -/* - * Procedure : Utopia_Free - * Purpose : Commit all values stored in the transaction if fCommit is true, free up context memory - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * fCommit - Commit transaction is true - * Return Values : - */ +/** +* @brief Free Utopia context and optionally commit pending transactions. +* +* Frees all transaction nodes, releases the read/write lock, and closes event handles. +* +* @param[in,out] pUtopiaCtx - UtopiaContext pointer. +* @param[in] fCommit - Commit transaction if true, discard changes if false. +* +* @return None. +*/ extern void Utopia_Free(UtopiaContext* pUtopiaCtx, int fCommit); #endif /* __UTCTX_H__ */ diff --git a/source/include/utctx/utctx_api.h b/source/include/utctx/utctx_api.h index 4a5507f2..93003b35 100644 --- a/source/include/utctx/utctx_api.h +++ b/source/include/utctx/utctx_api.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -50,7 +50,7 @@ #define UTOPIA_MAX_PASSWD_LENGTH 64 #define UTOPIA_MIN_PASSWD_LENGTH 1 #define UTOPIA_MAX_USERNAME_LENGTH 63 -#define UTOPIA_DEFAULT_ADMIN_PASSWD "admin" +#define UTOPIA_DEFAULT_ADMIN_PASSWD "admin" #define UTOPIA_DEFAULT_ADMIN_USER "admin" /* @@ -147,7 +147,7 @@ typedef enum _UtopiaValue UtopiaValue_Mgmt_WANIPrange_SrcEndIP, UtopiaValue_Mgmt_WANIPRange_SrcStartIP, UtopiaValue_Mgmt_WANIPrange_Desp, - UtopiaValue_Mgmt_WANIPrange_InsNum, + UtopiaValue_Mgmt_WANIPrange_InsNum, UtopiaValue_Mgmt_IGDEnabled, UtopiaValue_Mgmt_IGDUserConfig, UtopiaValue_Mgmt_IGDWANDisable, @@ -605,8 +605,8 @@ typedef enum _UtopiaValue UtopiaValue_USGv2_Lan_Clients_Count, UtopiaValue_USGv2_Lan_Clients, UtopiaValue_USGv2_Lan_Clients_Mac, - UtopiaValue_PNM_Status, - UtopiaValue_SPF_PrevRuleEnabledState, + UtopiaValue_PNM_Status, + UtopiaValue_SPF_PrevRuleEnabledState, UtopiaValue_PFR_PrevRuleEnabledState, UtopiaValue_PRT_PrevRuleEnabledState, UtopiaValue_HashPassword, @@ -637,329 +637,354 @@ typedef enum _UtopiaValue UtopiaValue__LAST__ } UtopiaValue; -/* - * Procedure : Utopia_GetKey - * Purpose : Retrieve a Utopia key - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * pszBuffer - Buffer to store output key string - * ccbBuf - Output buffer size - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Retrieve a Utopia key. +* +* @param[in] pUtopiaCtx - UtopiaContext pointer. +* @param[in] ixUtopia - UtopiaValue index. +* @param[out] pszBuffer - Buffer to store output key string. +* @param[in] ccbBuf - Output buffer size. +* +* @return The status of the operation. +* @retval 1 on success. +* @retval 0 on error. +*/ extern int Utopia_GetKey(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, char* pszBuffer, unsigned int ccbBuf); -/* - * Procedure : Utopia_GetIndexedKey - * Purpose : Retrieve a Utopia value with a key that is numerically indexed - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * iIndex - The numeric index of the key - * pszBuffer - Buffer to store output key string - * ccbBuf - Output buffer size - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Retrieve a Utopia key with a key that is numerically indexed. +* +* @param[in] pUtopiaCtx - UtopiaContext pointer. +* @param[in] ixUtopia - UtopiaValue index. +* @param[in] iIndex - The numeric index of the key. +* @param[out] pszBuffer - Buffer to store output key string. +* @param[in] ccbBuf - Output buffer size. +* +* @return The status of the operation. +* @retval 1 on success. +* @retval 0 on error. +*/ extern int Utopia_GetIndexedKey(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, int iIndex, char* pszBuffer, unsigned int ccbBuf); -/* - * Procedure : Utopia_GetIndexed2Key - * Purpose : Retrieve a Utopia value with a key that is two-dimensionally indexed - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * iIndex1 - The numeric index 1 - * iIndex2 - The numeric index 2 - * pszBuffer - Buffer to store output key string - * ccbBuf - Output buffer size - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Retrieve a Utopia key with a key that is two-dimensionally indexed. +* +* @param[in] pUtopiaCtx - UtopiaContext pointer. +* @param[in] ixUtopia - UtopiaValue index. +* @param[in] iIndex1 - The numeric index 1. +* @param[in] iIndex2 - The numeric index 2. +* @param[out] pszBuffer - Buffer to store output key string. +* @param[in] ccbBuf - Output buffer size. +* +* @return The status of the operation. +* @retval 1 on success. +* @retval 0 on error. +*/ extern int Utopia_GetIndexed2Key(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, int iIndex1, int iIndex2, char* pszBuffer, unsigned int ccbBuf); -/* - * Procedure : Utopia_GetNamedKey - * Purpose : Retrieve a Utopia key that is indexed with a string - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * pszName - Index string - * pszBuffer - Buffer to store output key string - * ccbBuf - Output buffer size - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Retrieve a Utopia key that is indexed with a string. +* +* @param[in] pUtopiaCtx - UtopiaContext pointer. +* @param[in] ixUtopia - UtopiaValue index. +* @param[in] pszName - Index string. +* @param[out] pszBuffer - Buffer to store output key string. +* @param[in] ccbBuf - Output buffer size. +* +* @return The status of the operation. +* @retval 1 on success. +* @retval 0 on error. +*/ extern int Utopia_GetNamedKey(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, char* pszName, char* pszBuffer, unsigned int ccbBuf); -/* - * Procedure : Utopia_GetNamed2Key - * Purpose : Retrieve Utopia key that is two-dimensionally indexed by strings - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * pszName1 - Index string 1 - * pszName2 - Index string 2 - * pszBuffer - Buffer to store output key string - * ccbBuf - Output buffer size - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Retrieve Utopia key that is two-dimensionally indexed by strings. +* +* @param[in] pUtopiaCtx - UtopiaContext pointer. +* @param[in] ixUtopia - UtopiaValue index. +* @param[in] pszName1 - Index string 1. +* @param[in] pszName2 - Index string 2. +* @param[out] pszBuffer - Buffer to store output key string. +* @param[in] ccbBuf - Output buffer size. +* +* @return The status of the operation. +* @retval 1 on success. +* @retval 0 on error. +*/ extern int Utopia_GetNamed2Key(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, char* pszName1, char* pszName2, char* pszBuffer, unsigned int ccbBuf); -/* - * Procedure : Utopia_Get - * Purpose : Retrieve a Utopia value - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * pszBuffer - Buffer to store output value string - * ccbBuf - Output buffer size - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Retrieve a Utopia value. +* +* @param[in] pUtopiaCtx - UtopiaContext pointer. +* @param[in] ixUtopia - UtopiaValue index. +* @param[out] pszBuffer - Buffer to store output value string. +* @param[in] ccbBuf - Output buffer size. +* +* @return The status of the operation. +* @retval 1 on success. +* @retval 0 on error. +*/ extern int Utopia_Get(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, char* pszBuffer, unsigned int ccbBuf); -/* - * Procedure : Utopia_GetAll - * Purpose : Returns all set values in the format '::=\n' - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * pszBuffer - Null-terminated return buffer - * ccbBuf - Size of the passed in return buffer - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Returns all set values in the format '::=\n' +* +* @param[in] pUtopiaCtx - UtopiaContext pointer. +* @param[out] pszBuffer - Null-terminated return buffer. +* @param[in] ccbBuf - Size of the passed in return buffer. +* +* @return The status of the operation. +* @retval 1 on success. +* @retval 0 on error. +*/ extern int Utopia_GetAll(UtopiaContext* pUtopiaCtx, char* pszBuffer, unsigned int ccbBuf); -/* - * Procedure : Utopia_GetIndexed - * Purpose : Retrieve a Utopia value with a key that is numerically indexed - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * iIndex - The numeric index of the key - * pszBuffer - Buffer to store output value string - * ccbBuf - Output buffer size - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Retrieve a Utopia value with a key that is numerically indexed. +* +* @param[in] pUtopiaCtx - UtopiaContext pointer. +* @param[in] ixUtopia - UtopiaValue index. +* @param[in] iIndex - The numeric index of the key. +* @param[out] pszBuffer - Buffer to store output value string. +* @param[in] ccbBuf - Output buffer size. +* +* @return The status of the operation. +* @retval 1 on success. +* @retval 0 on error. +*/ extern int Utopia_GetIndexed(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, int iIndex, char* pszBuffer, unsigned int ccbBuf); -/* - * Procedure : Utopia_GetIndexed2 - * Purpose : Retrieve a Utopia value with a key that is two-dimensionally indexed - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * iIndex1 - The numeric index 1 - * iIndex2 - The numeric index 2 - * pszBuffer - Buffer to store output value string - * ccbBuf - Output buffer size - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Retrieve a Utopia value with a key that is two-dimensionally indexed. +* +* @param[in] pUtopiaCtx - UtopiaContext pointer. +* @param[in] ixUtopia - UtopiaValue index. +* @param[in] iIndex1 - The numeric index 1. +* @param[in] iIndex2 - The numeric index 2. +* @param[out] pszBuffer - Buffer to store output value string. +* @param[in] ccbBuf - Output buffer size. +* +* @return The status of the operation. +* @retval 1 on success. +* @retval 0 on error. +*/ extern int Utopia_GetIndexed2(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, int iIndex1, int iIndex2, char* pszBuffer, unsigned int ccbBuf); -/* - * Procedure : Utopia_GetNamed - * Purpose : Retrieve a Utopia value with a key that is indexed with a string - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * pszName - Index string - * pszBuffer - Buffer to store output value string - * ccbBuf - Output buffer size - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Retrieve a Utopia value with a key that is indexed with a string. +* +* @param[in] pUtopiaCtx - UtopiaContext pointer. +* @param[in] ixUtopia - UtopiaValue index. +* @param[in] pszName - Index string. +* @param[out] pszBuffer - Buffer to store output value string. +* @param[in] ccbBuf - Output buffer size. +* +* @return The status of the operation. +* @retval 1 on success. +* @retval 0 on error. +*/ extern int Utopia_GetNamed(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, char* pszName, char* pszBuffer, unsigned int ccbBuf); -/* - * Procedure : Utopia_GetNamed2 - * Purpose : Retrieve a Utopia value with a key that is two-dimensionally indexed by strings - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * pszName1 - Index string 1 - * pszName2 - Index string 2 - * pszBuffer - Buffer to store output value string - * ccbBuf - Output buffer size - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Retrieve a Utopia value with a key that is two-dimensionally indexed by strings. +* +* @param[in] pUtopiaCtx - UtopiaContext pointer. +* @param[in] ixUtopia - UtopiaValue index. +* @param[in] pszName1 - Index string 1. +* @param[in] pszName2 - Index string 2. +* @param[out] pszBuffer - Buffer to store output value string. +* @param[in] ccbBuf - Output buffer size. +* +* @return The status of the operation. +* @retval 1 on success. +* @retval 0 on error. +*/ extern int Utopia_GetNamed2(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, char* pszName1, char* pszName2, char* pszBuffer, unsigned int ccbBuf); -/* - * Procedure : Utopia_RawGet - * Purpose : Retrieve a raw non-Utopia value (UtopiaValue doesn't exist) - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * pszNamespace - Namespace of the value retrieved - * pszKey - Key of the value being retrieved - * pszBuffer - Buffer to store output value string - * ccbBuf - Output buffer size - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Retrieve a raw non-Utopia value( (UtopiaValue doesn't exist)) +* +* @param[in] pUtopiaCtx - UtopiaContext pointer. +* @param[in] pszNamespace - Namespace of the value retrieved. +* @param[in] pszKey - Key of the value being retrieved. +* @param[out] pszBuffer - Buffer to store output value string. +* @param[in] ccbBuf - Output buffer size. +* +* @return The status of the operation. +* @retval 1 on success. +* @retval 0 on error. +*/ extern int Utopia_RawGet(UtopiaContext* pUtopiaCtx, char* pszNamespace, char* pszKey, char* pszBuffer, unsigned int ccbBuf); -/* - * Procedure : Utopia_RawSet - * Purpose : Set a raw non-Utopia value (UtopiaValue doesn't exist) - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * pszNamespace - Namespace of value being set - * pszKey - Key of value being set - * pszValue - Value being set - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Set a raw non-Utopia value (UtopiaValue doesn't exist). +* +* @param[in] pUtopiaCtx - UtopiaContext pointer. +* @param[in] pszNamespace - Namespace of value being set. +* @param[in] pszKey - Key of value being set. +* @param[in] pszValue - Value being set. +* +* @return The status of the operation. +* @retval 1 on success. +* @retval 0 on error. +*/ extern int Utopia_RawSet(UtopiaContext* pUtopiaCtx, char* pszNamespace, char* pszKey, char* pszValue); -/* - * Procedure : Utopia_Set - * Purpose : Set a Utopia value - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * pszValue - Value being set - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Set a Utopia value. +* +* @param[in] pUtopiaCtx - UtopiaContext pointer. +* @param[in] ixUtopia - UtopiaValue index. +* @param[in] pszValue - Value being set. +* +* @return The status of the operation. +* @retval 1 on success. +* @retval 0 on error. +*/ extern int Utopia_Set(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, char* pszValue); -/* - * Procedure : Utopia_SetAll - * Purpose : Sets all of the values in the input buffer, which should be formatted '::=\n'. - * : Passing in a null buffer will result in all values being set to factory defaults. - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * pszBuffer - Null-terminated input buffer - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Sets all of the values in the input buffer. +* +* This function sets all of the values in the input buffer, which should be formatted '::=\n'. +* Passing in a null buffer will result in all values being set to factory defaults. +* +* @param[in] pUtopiaCtx - UtopiaContext pointer. +* @param[in] pszBuffer - Null-terminated input buffer. +* +* @return The status of the operation. +* @retval 1 on success. +* @retval 0 on error. +*/ extern int Utopia_SetAll(UtopiaContext* pUtopiaCtx, char* pszBuffer); -/* - * Procedure : Utopia_SetIndexed - * Purpose : Set a Utopia value with a key that is numerically indexed - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * pszValue - Value being set - * iIndex - The numeric index - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Set a Utopia value with a key that is numerically indexed. +* +* @param[in] pUtopiaCtx - UtopiaContext pointer. +* @param[in] ixUtopia - UtopiaValue index. +* @param[in] iIndex - The numeric index. +* @param[in] pszValue - Value being set. +* +* @return The status of the operation. +* @retval 1 on success. +* @retval 0 on error. +*/ extern int Utopia_SetIndexed(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, int iIndex, char* pszValue); -/* - * Procedure : Utopia_SetIndexed2 - * Purpose : Set a Utopia value with a key that is two-dimensionally indexed - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * iIndex1 - The numeric index 1 - * iIndex2 - The numeric index 2 - * pszValue - Value being set - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Set a Utopia value with a key that is two-dimensionally indexed. +* +* @param[in] pUtopiaCtx - UtopiaContext pointer. +* @param[in] ixUtopia - UtopiaValue index. +* @param[in] iIndex1 - The numeric index 1. +* @param[in] iIndex2 - The numeric index 2. +* @param[in] pszValue - Value being set. +* +* @return The status of the operation. +* @retval 1 on success. +* @retval 0 on error. +*/ extern int Utopia_SetIndexed2(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, int iIndex1, int iIndex2, char* pszValue); -/* - * Procedure : Utopia_SetNamed - * Purpose : Set a Utopia value with a key that is indexed with a string - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * pszName - Index string - * pszValue - Value being set - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Set a Utopia value with a key that is indexed with a string. +* +* @param[in] pUtopiaCtx - UtopiaContext pointer. +* @param[in] ixUtopia - UtopiaValue index. +* @param[in] pszName - Index string. +* @param[in] pszValue - Value being set. +* +* @return The status of the operation. +* @retval 1 on success. +* @retval 0 on error. +*/ extern int Utopia_SetNamed(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, char* pszName, char* pszValue); -/* - * Procedure : Utopia_SetNamed2 - * Purpose : Set a Utopia value with a key that is two-dimensionally indexed by strings - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * pszName1 - Index string 1 - * pszName2 - Index string 2 - * pszValue - Value being set - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Set a Utopia value with a key that is two-dimensionally indexed by strings. +* +* @param[in] pUtopiaCtx - UtopiaContext pointer. +* @param[in] ixUtopia - UtopiaValue index. +* @param[in] pszName1 - Index string 1. +* @param[in] pszName2 - Index string 2. +* @param[in] pszValue - Value being set. +* +* @return The status of the operation. +* @retval 1 on success. +* @retval 0 on error. +*/ extern int Utopia_SetNamed2(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, char* pszName1, char* pszName2, char* pszValue); -/* - * Procedure : Utopia_Unset - * Purpose : Unset a Utopia value - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * pszValue - Value being set - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Unset a Utopia value. +* +* @param[in] pUtopiaCtx - UtopiaContext pointer. +* @param[in] ixUtopia - UtopiaValue index. +* +* @return The status of the operation. +* @retval 1 on success. +* @retval 0 on error. +*/ extern int Utopia_Unset(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia); -/* - * Procedure : Utopia_UnsetIndexed - * Purpose : Unset a Utopia value with a key that is numerically indexed - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * iIndex - The numeric index - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Unset a Utopia value with a key that is numerically indexed. +* +* @param[in] pUtopiaCtx - UtopiaContext pointer. +* @param[in] ixUtopia - UtopiaValue index. +* @param[in] iIndex - The numeric index. +* +* @return The status of the operation. +* @retval 1 on success. +* @retval 0 on error. +*/ extern int Utopia_UnsetIndexed(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, int iIndex); -/* - * Procedure : Utopia_UnsetIndexed2 - * Purpose : Unset a Utopia value with a key that is two-dimensionally indexed - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * iIndex1 - The numeric index 1 - * iIndex2 - The numeric index 2 - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Unset a Utopia value with a key that is two-dimensionally indexed. +* +* @param[in] pUtopiaCtx - UtopiaContext pointer. +* @param[in] ixUtopia - UtopiaValue index. +* @param[in] iIndex1 - The numeric index 1. +* @param[in] iIndex2 - The numeric index 2. +* +* @return The status of the operation. +* @retval 1 on success. +* @retval 0 on error. +*/ extern int Utopia_UnsetIndexed2(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, int iIndex1, int iIndex2); -/* - * Procedure : Utopia_UnsetNamed - * Purpose : Unset a Utopia value with a key that is indexed with a string - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * pszName - Index string - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Unset a Utopia value with a key that is indexed with a string. +* +* @param[in] pUtopiaCtx - UtopiaContext pointer. +* @param[in] ixUtopia - UtopiaValue index. +* @param[in] pszName - Index string. +* +* @return The status of the operation. +* @retval 1 on success. +* @retval 0 on error. +*/ extern int Utopia_UnsetNamed(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, char* pszName); -/* - * Procedure : Utopia_UnsetNamed2 - * Purpose : Unset a Utopia value with a key that is two-dimensionally indexed by strings - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * pszName1 - Index string 1 - * pszName2 - Index string 2 - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Unset a Utopia value with a key that is two-dimensionally indexed by strings. +* +* @param[in] pUtopiaCtx - UtopiaContext pointer. +* @param[in] ixUtopia - UtopiaValue index. +* @param[in] pszName1 - Index string 1. +* @param[in] pszName2 - Index string 2. +* +* @return The status of the operation. +* @retval 1 on success. +* @retval 0 on error. +*/ extern int Utopia_UnsetNamed2(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, char* pszName1, char* pszName2); /* - * Utopia_Events are infered from UtopiaValue sets, so you shouldn't need to use + * Utopia_Events are inferred from UtopiaValue sets, so you shouldn't need to use * these unless you need to trigger an event without setting an UtopiaValue value. */ typedef enum _Utopia_Event @@ -991,15 +1016,16 @@ typedef enum _Utopia_Event Utopia_Event__LAST__ = 0x200000 } Utopia_Event; -/* - * Procedure : Utopia_SetEvent - * Purpose : Set a Utopia event to be triggered on context free - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * event - Utopia event to be triggered - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Set a Utopia event to be triggered on context free. +* +* @param[in] pUtopiaCtx - UtopiaContext pointer. +* @param[in] event - Utopia event to be triggered. +* +* @return The status of the operation. +* @retval 1 on success. +* @retval 0 on error. +*/ extern int Utopia_SetEvent(UtopiaContext* pUtopiaCtx, Utopia_Event event); -#endif /* __UTCTX_API_H__ */ +#endif /* __UTCTX_API_H__ */ \ No newline at end of file diff --git a/source/include/utctx/utctx_rwlock.h b/source/include/utctx/utctx_rwlock.h index 0d20e52d..690bd9c5 100644 --- a/source/include/utctx/utctx_rwlock.h +++ b/source/include/utctx/utctx_rwlock.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -64,53 +64,71 @@ typedef struct _UtopiaRWLock } UtopiaRWLock; -/* - * Procedure : UtopiaRWLock_Init - * Purpose : Initialize Utopia rwlock - * Parameters : - * pLock - UtopiaRWLock pointer - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Initialize Utopia read/write lock. +* +* Initializes the read and write lock flags to 0 and calls the underlying +* read-write semaphore initialization routine. +* +* @param[in,out] pLock - UtopiaRWLock pointer. +* +* @return The status of the operation. +* @retval 1 on success. +* @retval 0 on error. +*/ extern int UtopiaRWLock_Init(UtopiaRWLock* pLock); -/* - * Procedure : UtopiaRWLock_Destroy - * Purpose : Destroy Utopia rwlock - * Parameters : - * pLock - UtopiaRWLock pointer - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Destroy Utopia read/write lock. +* +* Destroys the underlying read-write semaphore and releases associated resources. +* +* @param[in,out] pLock - UtopiaRWLock pointer. +* +* @return The status of the operation. +* @retval 1 on success. +* @retval 0 on error. +*/ extern int UtopiaRWLock_Destroy(UtopiaRWLock* pLock); -/* - * Procedure : UtopiaRWLock_ReadLock - * Purpose : Acquires a read lock if there isn't already a read or a write lock. - * Parameters : - * pLock - UtopiaRWLock pointer - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Acquire a read lock. +* +* Acquires a read lock if there isn't already a read or a write lock. +* If a read or write lock is already held, the function returns success immediately. +* +* @param[in,out] pLock - UtopiaRWLock pointer. +* +* @return The status of the operation. +* @retval 1 on success. +* @retval 0 on error. +*/ extern int UtopiaRWLock_ReadLock(UtopiaRWLock* pLock); -/* - * Procedure : UtopiaRWLock_WriteLock - * Purpose : Acquires a write lock if there isn't already a write lock. If there is a read lock, it will be released. - * Parameters : - * pLock - UtopiaRWLock pointer - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Acquire a write lock. +* +* Acquires a write lock if there isn't already a write lock. +* If there is a read lock, it will be released before acquiring the write lock. +* +* @param[in,out] pLock - UtopiaRWLock pointer. +* +* @return The status of the operation. +* @retval 1 on success. +* @retval 0 on error. +*/ extern int UtopiaRWLock_WriteLock(UtopiaRWLock* pLock); -/* - * Procedure : UtopiaRWLock_Free - * Purpose : Release locks and free up resources - * Parameters : - * pLock - UtopiaRWLock pointer - * Return Values : - */ +/** +* @brief Release locks and free up resources. +* +* Releases any held read or write locks and closes the read-write semaphores. +* Resets the read and write lock flags to 0. +* +* @param[in,out] pLock - UtopiaRWLock pointer. +* +* @return None. +*/ extern void UtopiaRWLock_Free(UtopiaRWLock* pLock); #endif /* __UTCTX_RWLOCK_H__ */ diff --git a/source/pal/kernel/include/pal_kernel.h b/source/pal/kernel/include/pal_kernel.h index 2d5dac34..3a07b4a8 100644 --- a/source/pal/kernel/include/pal_kernel.h +++ b/source/pal/kernel/include/pal_kernel.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -62,35 +62,31 @@ #define MAC_ADDRESS_LEN 6 #define IF_NAME_LEN 16 -/************************************************************ -* Function: PAL_get_if_IpAddress +/** +* @brief Get the IP address of a network interface. * -* Parameters: -* ifName: IN. the interface name. -* -* IpAddress: INOUT. the ipaddress of the interface -* -* Description: -* This function get the ipaddress of the interface ifName. +* This function retrieves the IPv4 address of the specified network interface. * -* Return Values: INT32 -* 0 if successful else error code. -************************************************************/ +* @param[in] ifName - The interface name. +* @param[in,out] IpAddress - Buffer to store the IP address of the interface. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval -1 if error code. +*/ INT32 PAL_get_if_IpAddress(IN const CHAR *ifName, INOUT CHAR IpAddress[IP_ADDRESS_LEN]); -/************************************************************ -* Function: PAL_get_if_MacAddress + +/** +* @brief Get the MAC address of a network interface. +* +* This function retrieves the hardware (MAC) address of the specified network interface. * -* Parameters: -* ifName: IN. the interface name. -* -* IpAddress: INOUT. the mac of the interface -* -* Description: -* This function get the mac of the interface ifName. +* @param[in] ifName - The interface name. +* @param[in,out] MacAddress - Buffer to store the MAC address of the interface. * -* Return Values: INT32 -* 0 if successful else error code. -************************************************************/ +* @return The status of the operation. +* @retval 0 if successful. +* @retval -1 if error code. +*/ INT32 PAL_get_if_MacAddress(IN const CHAR *ifName, INOUT CHAR MacAddress[MAC_ADDRESS_LEN]); -#endif/*PAL_KERNEL_H*/ - +#endif/*PAL_KERNEL_H*/ \ No newline at end of file diff --git a/source/pal/log/include/pal_log.h b/source/pal/log/include/pal_log.h index 3b2d6d22..e696aa10 100644 --- a/source/pal/log/include/pal_log.h +++ b/source/pal/log/include/pal_log.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -49,7 +49,36 @@ typedef enum log_level_s typedef VOID (*pal_log_show_module_debug_info_callback_t) (CHAR* input_string); +/** +* @brief Register a module for logging. +* +* This function registers a module with the logging system by creating a local Unix UDP socket +* for the module and establishing communication with the log router transmitter. +* +* @param[in] module_name - The name of the module to register. +* @param[in] log_show_module_debug_info_func - Callback function to display module debug information. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval -1 if error (invalid module name, initialization failure, or maximum module count exceeded). +*/ extern INT32 PAL_log_register(CHAR * module_name, pal_log_show_module_debug_info_callback_t log_show_module_debug_info_func); + +/** +* @brief Log a message with specified level and format. +* +* This function formats and sends a log message to the log router transmitter. +* The log message includes module name, log level, file name, line number, and user-formatted content. +* +* @param[in] module_name - The name of the module generating the log. +* @param[in] level_number - The log level. +* @param[in] file - The source file name. +* @param[in] line - The line number. +* @param[in] fmt - Printf-style format string. +* @param[in] ... - Variable arguments matching the format string. +* +* @return None. +*/ extern VOID PAL_log (CHAR* module_name, UINT32 level_number, CHAR *file, UINT32 line, const CHAR *fmt, ... ); #ifdef PAL_LOG_ENABLE @@ -65,8 +94,7 @@ extern VOID PAL_log (CHAR* module_name, UINT32 level_number, CHAR *file, UINT32 #else #define PAL_LOG_REGISTER(module_name, log_show_module_debug_info_func) -#define PAL_LOG(module_name, level_number, fmt... ) +#define PAL_LOG(module_name, level_number, fmt... ) #endif -#endif/*#ifndef PAL_LOG_H*/ - +#endif/*#ifndef PAL_LOG_H*/ \ No newline at end of file diff --git a/source/pal/log/src/pal_log_internal.h b/source/pal/log/src/pal_log_internal.h index be5aa4d7..53182667 100644 --- a/source/pal/log/src/pal_log_internal.h +++ b/source/pal/log/src/pal_log_internal.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -72,7 +72,7 @@ #include "pal_log.h" -#define IN +#define IN #define OUT /*************************************************************************** @@ -216,25 +216,85 @@ typedef struct socket_info_s{ packet_handle_func_t packet_handle_func; }socket_info_t; +/** +* @brief Initialize a local Unix domain UDP socket. +* +* Creates UDP socket and binds it to the specified Unix domain socket path. +* +* @param[in] socket_addr_path_this_end - The Unix domain socket path to bind to. +* @param[out] unix_socket - Pointer to store the created socket file descriptor. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval -1 if error (socket creation, path assignment, or bind failure). +*/ extern INT32 PAL_log_init_local_unix_udp_socket(IN CHAR* socket_addr_path_this_end, OUT INT32* unix_socket); +/** +* @brief Initialize a Unix domain socket address structure for communication. +* +* This function prepares a sock address structure with the specified Unix domain socket path for sending +* messages to another local endpoint. +* +* @param[in] socket_addr_path_other_end - The Unix domain socket path of the destination. +* @param[out] socket_addr_other_end - Pointer to the sockaddr_un structure to initialize. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval -1 if error (path assignment failure). +*/ extern INT32 PAL_log_init_local_unix_udp_socket_to_addr(IN CHAR *socket_addr_path_other_end, OUT struct sockaddr_un *socket_addr_other_end); +/** +* @brief Initialize an Internet domain UDP socket. +* +* This function creates UDP datagram socket and binds it to the specified port on all interfaces. +* +* @param[in] port - The UDP port number to bind to. +* @param[out] udp_socket - Pointer to store the created socket file descriptor. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval -1 if error (socket creation or bind failure). +*/ extern INT32 PAL_log_init_inet_udp_socket(IN UINT16 port, OUT INT32* udp_socket); +/** +* @brief Initialize an Internet domain socket address structure for communication. +* +* This function prepares a sock address structure with the specified IP address and port +* for sending messages to a remote endpoint. +* +* @param[in] socket_ip_addr_other_end - The IP address of the destination. +* @param[in] port - The UDP port number of the destination. +* @param[out] socket_addr_other_end - Pointer to the sockaddr_in structure to initialize. +* +* @return The status of the operation. +* @retval 0 if successful. +*/ extern INT32 PAL_log_init_inet_udp_socket_to_addr(IN ULONG socket_ip_addr_other_end,/*network order*/ IN UINT16 port, OUT struct sockaddr_in *socket_addr_other_end); -extern VOID PAL_log_recv_and_process_packets(IN socket_info_t *socket_info_array, IN INT32 socket_count); +/** +* @brief Receive and process packets from multiple sockets. +* +* This function monitor multiple sockets and dispatches received packets to their respective handler functions. +* +* @param[in] socket_info_array - Array of socket info structures containing socket descriptors and handlers. +* @param[in] socket_count - Number of sockets in the array. +* +* @return None. +*/ +extern VOID PAL_log_recv_and_process_packets(IN socket_info_t *socket_info_array, IN INT32 socket_count); -#endif/*#ifndef LOG_INTERNAL_H*/ +#endif/*#ifndef LOG_INTERNAL_H*/ \ No newline at end of file diff --git a/source/pal/upnp/include/pal_upnp.h b/source/pal/upnp/include/pal_upnp.h index 3ddce0ff..fd2e8540 100644 --- a/source/pal/upnp/include/pal_upnp.h +++ b/source/pal/upnp/include/pal_upnp.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -41,31 +41,31 @@ *****************************************************************************/ /******************************************************************************* * - * Copyright (c) 2000-2003 Intel Corporation - * All rights reserved. + * Copyright (c) 2000-2003 Intel Corporation + * All rights reserved. * - * Redistribution and use in source and binary forms, with or without - * modification, are permitted provided that the following conditions are met: + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: * - * - Redistributions of source code must retain the above copyright notice, - * this list of conditions and the following disclaimer. - * - Redistributions in binary form must reproduce the above copyright notice, - * this list of conditions and the following disclaimer in the documentation - * and/or other materials provided with the distribution. - * - Neither name of Intel Corporation nor the names of its contributors - * may be used to endorse or promote products derived from this software + * - Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * - Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * - Neither name of Intel Corporation nor the names of its contributors + * may be used to endorse or promote products derived from this software * without specific prior written permission. - * - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL OR - * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, - * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, - * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR - * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL OR + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING - * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. * ******************************************************************************/ @@ -168,8 +168,8 @@ typedef CHAR pal_upnp_sid[PAL_UPNP_SID_SIZE]; /*for event callback function*/ typedef INT32 (*pal_upnp_func)( - IN Upnp_EventType event_type, - IN VOID *event, + IN Upnp_EventType event_type, + IN VOID *event, IN VOID *cookie); typedef struct{ @@ -205,7 +205,7 @@ typedef struct{ /** The DOM document containing the information from the the SOAP header. */ pal_xml_top *soap_header; - + }pal_upnp_action_request; /** Represents the request for current value of a state variable in a service @@ -226,7 +226,7 @@ typedef struct{ CHAR statvar_name[PAL_UPNP_NAME_SIZE]; /** IP address of sender requesting the state variable. */ struct in_addr cp_addr; - /** The current value of the variable. This needs to be allocated by + /** The current value of the variable. This needs to be allocated by * the caller. When finished with it, the SDK frees this {\bf DOMString}. */ CHAR* CurrentVal; }pal_upnp_state_var_request; @@ -234,218 +234,190 @@ typedef struct{ typedef struct{ /** The identifier for the service being subscribed to. */ - CHAR *ServiceId; + CHAR *ServiceId; /** Universal device name. */ - CHAR *UDN; + CHAR *UDN; /** The assigned subscription ID for this subscription. */ pal_upnp_sid Sid; }pal_upnp_subscription_request; - -/************************************************************ - * Function: PAL_upnp_init - * - * Parameters: - * lo_ip: Input. Local IP Address. - * If input is NULL, an appropriate IP address will be automatically selected. - * lo_port: Input . Local Port to listen for incoming connections. - * If input is NULL, a appropriate port will be automatically selected. - * - * Description: - * Start UPnP Stack - Initialization. - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ +/** +* @brief Initialize the UPnP stack. +* +* Starts the UPnP library initialization with the specified interface and port. +* +* @param[in] lo_ip - Local IP address or interface name. NULL for automatic selection. +* \n If lo_ip is NULL, an appropriate IP address will be automatically selected. +* @param[in] lo_port - Local port to listen for incoming connections. 0 for automatic selection. +* \n If lo_port is 0, an appropriate port will be automatically selected. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval Error code if initialization fails. +*/ INT32 PAL_upnp_init(IN const CHAR *lo_ip, IN UINT16 lo_port); - -/************************************************************ - * Function: PAL_upnp_get_ipaddress - * - * Parameters: - * - * Description: - * Gives back the local ipaddress. - * - * Return Values: INT32 - * return the IP address string on success else NULL of failure - ************************************************************/ +/** +* @brief Get the local IP address. +* +* Returns the IP address string of the UPnP server. +* +* @return The ip address. +* @retval The IP address string on success. +* @retval NULL on failure. +*/ CHAR *PAL_upnp_get_ipaddress(); -/************************************************************ - * Function: PAL_upnp_get_ip6address - * - * Parameters: - * - * Description: - * Gives back the local ipv6 address. - * - * Return Values: INT32 - * return the IPv6 address string on success else NULL of failure - ************************************************************/ +/** +* @brief Get the local IPv6 address. +* +* Returns the IPv6 address string of the UPnP server. +* +* @return The IPv6 address. +* @retval The IPv6 address string on success. +* @retval NULL on failure. +*/ CHAR *PAL_upnp_get_ip6address(); -/************************************************************ - * Function: PAL_upnp_get_port - * - * Parameters: - * - * Description: - * Gives back the port for listening ssdp. - * - * Return Values: INT32 - * return the port number on success else 0 of failure - ************************************************************/ +/** +* @brief Get the UPnP server port. +* +* Returns the port number used by the UPnP server for listening to SSDP. +* +* @return The port number. +* @retval The port number on success. +* @retval 0 on failure. +*/ UINT16 PAL_upnp_get_port(); - -/************************************************************ - * Function: PAL_upnp_register_root_device - * - * Parameters: - * lo_path: Input. Local path for device description file. - * file_name: Input. File name of device description file. - * func: Input. Callback functions for device events - * cookie: Input. Reserved. - * handle: Output. Device handle. - * - * Description: - * This function registers a device application with - * the UPnP Library. A device application cannot make any other API - * calls until it registers using this function. - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ +/** +* @brief Register a root device with the UPnP library. +* +* Registers a device application with the UPnP library using the device description file. +* \n Sets the web server root directory and creates the device description URL. +* \n A device application cannot make any other API calls until it registers using this function. +* \n This path also serves as the web root directory. +* +* @param[in] lo_path - Local path for device description file. NULL for default web directory. +* @param[in] file_name - File name of device description file. +* @param[in] func - Callback function for device events. +* @param[in] cookie - Reserved for future use. +* @param[out] handle - Pointer to store the device handle. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval Error code if registration fails. +*/ INT32 PAL_upnp_register_root_device(IN const CHAR *lo_path, IN const CHAR *file_name, IN pal_upnp_func func, IN const VOID *cookie, OUT pal_upnp_device_handle *handle); - -/************************************************************ - * Function: PAL_upnp_unregister_root_device - * - * Parameters: - * handle: Input. Device handle. - * - * Description: - * This function unregisters a root device registered with - * PAL_upnp_register_root_device. After this call, the - * pal_upnp_device_handle handle is no longer valid. For all advertisements that - * have not yet expired, the UPnP library sends a device unavailable message - * automatically. - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ +/** +* @brief Unregister a root device from the UPnP library. +* +* Unregisters a root device registered with PAL_upnp_register_root_device. +* \n After this call, the pal_upnp_device_handle is no longer valid. +* \n For all advertisements that have not yet expired, the UPnP library sends +* \n a device unavailable message automatically. +* +* @param[in] handle - Device handle to unregister. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval Error code if unregistration fails. +*/ INT32 PAL_upnp_unregister_root_device(IN pal_upnp_device_handle handle); - - -/************************************************************ - * Function: PAL_upnp_send_advertisement - * - * Parameters: - * handle: Input. Handle for device instance. - * expire: Input. Timer of seconds for resending the advertisement. - * - * Description: - * This function sends the device advertisement. It also schedules a - * job for the next advertisement after "expire" time. - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ +/** +* @brief Send device advertisement. +* +* Sends the UPnP device advertisement and schedules a job for the next +* \n advertisement after the specified expire time. +* +* @param[in] handle - Handle for device instance. +* @param[in] expire - Time in seconds for resending the advertisement. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval Error code if advertisement fails. +*/ INT32 PAL_upnp_send_advertisement(IN pal_upnp_device_handle handle, IN INT32 expire); - -/************************************************************ - * Function: PAL_upnp_register_cp - * - * Parameters: - * func: Input. Pointer to a function for receiving - * asynchronous events. - * cookie: Input. Reserved. - * handle: Output. Pointer to a variable to store - * the new control point handle. - * - * Description: - * This function registers a control point application with the - * UPnP Library. A control point application cannot make any other API - * calls until it registers using this function. - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ +/** +* @brief Register a control point with the UPnP library. +* +* Registers a control point application with the UPnP library for receiving asynchronous events. +* \n A control point application cannot make any other API calls until it registers using this function. +* +* @param[in] func - Pointer to a callback function for receiving asynchronous events. +* @param[in] cookie - Reserved for future use. +* @param[out] handle - Pointer to store the new control point handle. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval Error code if registration fails. +*/ INT32 PAL_upnp_register_cp (IN pal_upnp_func func, IN const VOID *cookie, OUT pal_upnp_cp_handle *handle); - -/************************************************************ - * Function: PAL_upnp_unregister_cp - * - * Parameters: - * handle: Input. The handle of the control point instance - * to unregister. - * - * Description: - * This function unregisters a client registered with - * PAL_upnp_register_cp. After this call, the - * pal_upnp_cp_handle handle is no longer valid. The UPnP Library generates - * no more callbacks after this function returns. - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ +/** +* @brief Unregister a control point from the UPnP library. +* +* Unregisters a client registered with PAL_upnp_register_cp. +* \n After this call, the pal_upnp_cp_handle is no longer valid. +* \n The UPnP library generates no more callbacks after this function returns. +* +* @param[in] handle - The handle of the control point instance to unregister. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval Error code if unregistration fails. +*/ INT32 PAL_upnp_unregister_cp(IN pal_upnp_cp_handle handle); - -/************************************************************ - * Function: PAL_upnp_search_async - * - * Parameters: - * handle: Input. The handle of the control point instance - * max_timeout: Input. Maximum time to wait for the search reply. - * target: Input. Search target string. - * cookie: Input. Reserved. - * - * Description: - * This function searches for the devices for the provided maximum time. - * It is a asynchronous function. It schedules a search job and returns. - * control point is notified about the search results after search timer. - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ + /** +* @brief Search for devices asynchronously. +* +* Searches for UPnP devices for the specified maximum time. +* \n This is an asynchronous function that schedules a search job and returns immediately. +* \n The control point is notified about search results through callbacks after the search timer expires. +* +* @param[in] handle - The handle of the control point instance. +* @param[in] max_timeout - Maximum time in seconds to wait for search replies. +* @param[in] target - Search target string. +* @param[in] cookie - Reserved for future use. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval Error code if search initiation fails. +*/ INT32 PAL_upnp_search_async(IN pal_upnp_cp_handle handle, IN INT32 max_timeout, IN const CHAR *target, IN const VOID *cookie); -/************************************************************ - * Function: PAL_upnp_make_action - * - * Parameters: - * action: InputOutput. Action buffer. - * action_name: Input. Action name. - * service_type: Input. Service Type. - * nb_params: Input. Number of pairs of parameters. - * params: Input. Parameter pairs array. - * action_type: Input. Request or response. - * - * Description: - * This function creates the action(request/response) from the argument - * list.This function creates the action request or response if it is a first - * argument else it will add the argument in the document. - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ +/** +* @brief Create a UPnP action request or response. +* +* Creates an action document (request or response) from the argument list. +* \n This function creates the action request or response if it is a first +* \n argument else it will add the argument in the document. +* +* @param[in,out] action - Pointer to action buffer. NULL to create new, existing to add arguments. +* @param[in] action_name - Action name. +* @param[in] service_type - Service type string. +* @param[in] nb_params - Number of parameter pairs. +* @param[in] params - Array of parameter name-value pairs. +* @param[in] action_type - Request or response as PAL_UPNP_ACTION_REQUEST or PAL_UPNP_ACTION_RESPONSE. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval -1 if error (invalid parameters or action creation fails). +*/ INT32 PAL_upnp_make_action( INOUT pal_xml_top** action, IN const CHAR *action_name, IN const CHAR *service_type, @@ -454,26 +426,23 @@ INT32 PAL_upnp_register_root_device(IN const CHAR *lo_path, IN pal_upnp_action_type action_type); -/************************************************************ - * Function: PAL_upnp_send_action - * - * Parameters: - * handle: Input. Handle of control point to send action. - * action_url: Input. The action URL of service. - * service_type: Input. The type of the service. - * action: Input. The top structure for action. - * response: The top structure for the response - * to the action. The UPnP Library allocates this buffer - * and the caller needs to free it. - * - * Description: - * This function sends a message to change a state variable in a service. - * This is a synchronous call that does not return until the action is - * complete. - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ +/** +* @brief Send a UPnP action to a service. +* +* Sends a SOAP message to change a state variable in a service. +* \n This is a synchronous call that does not return until the action is complete. +* \n The UPnP library allocates the response buffer and the caller needs to free it. +* +* @param[in] handle - Handle of control point to send action. +* @param[in] action_url - The action URL of the service. +* @param[in] service_type - The type of the service. +* @param[in] action - The action document structure. +* @param[out] response - Pointer to store the response document structure. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval Error code if action fails. +*/ INT32 PAL_upnp_send_action( IN pal_upnp_cp_handle handle, IN const CHAR *action_url, IN const CHAR *service_type, @@ -481,112 +450,96 @@ INT32 PAL_upnp_register_root_device(IN const CHAR *lo_path, OUT pal_xml_top **response); -/************************************************************ - * Function: PAL_upnp_download_xmldoc - * - * Parameters: - * url: Input. Device description url for file downloading. - * xml_top: Output. The buffer to strore device description file. - * The UPnP Library allocates this buffer - * and the caller needs to free it - * - * Description: - * This function sends a message to change a state variable in a service. - * This is a synchronous call that does not return until the action is - * complete. - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ +/** +* @brief Download an XML document from a URL. +* +* Downloads and parses a device description or service description file from the specified URL. +* \n This is a synchronous call that does not return until the download is complete. +* \n The UPnP library allocates the xml_top buffer and the caller needs to free it. +* +* @param[in] url - Device or service description URL for file downloading. +* @param[out] xml_top - Pointer to store the parsed XML document structure. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval Error code if download or parsing fails. +*/ INT32 PAL_upnp_download_xmldoc(IN const CHAR *url, OUT pal_xml_top **xml_top); -/************************************************************ - * Function: PAL_upnp_resolve_url - * - * Parameters: - * base_url: Input. Base URL string. - * rel_url: Input. Relative URL string. - * abs_url: Output. Absolute URL string. - * - * Description: - * This functions concatinates the base URL and relative URL to generate -* the absolute URL. - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ +/** +* @brief Resolve a relative URL to an absolute URL. +* +* Concatenates the base URL and relative URL to generate the absolute URL. +* \n The UPnP library allocates the abs_url buffer and the caller needs to free it. +* +* @param[in] base_url - Base URL string. +* @param[in] rel_url - Relative URL string. +* @param[out] abs_url - Pointer to store the resolved absolute URL string. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval Error code if URL resolution fails. +*/ INT32 PAL_upnp_resolve_url(IN const CHAR *base_url, IN const CHAR *rel_url, OUT CHAR **abs_url); -/************************************************************ - * Function: PAL_upnp_finish - * - * Parameters: - * - * - * Description: - * Stop the UPnP library working and clean resources. - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ +/** +* @brief Stop the UPnP library and clean up resources. +* +* Terminates the UPnP library operation and frees all allocated resources. +* \n Should be called when the application no longer needs UPnP functionality. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval Error code if cleanup fails. +*/ INT32 PAL_upnp_finish(); -/************************************************************ - * Function: PAL_upnp_subscribe - * - * Parameters: - * handle: Input. Handle of the control point to register event. - * event_url: Input. The URL of the service to subscribe to. - * timeout: Input/Output. Pointer to a variable containing the requested - * subscription time. Upon return, it contains the - * actual subscription time returned from the service. - * sid: Output. Pointer to a variable to receive the - * subscription ID (SID) - * - * Description: - * This function registers a control point to receive event - * notifications from another device. This operation is synchronous - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ +/** +* @brief Subscribe to receive event notifications from a service. +* +* Registers a control point to receive event notifications from another device. +* \n This operation is synchronous and does not return until subscription is complete. +* \n Upon return, timeout contains the actual subscription time returned from the service. +* +* @param[in] handle - Handle of the control point to register event. +* @param[in] event_url - The URL of the service to subscribe to. +* @param[in,out] timeout - Pointer to requested subscription time in seconds. Returns actual subscription time. +* @param[out] sid - Pointer to store the subscription ID (SID). +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval Error code if subscription fails. +*/ INT32 PAL_upnp_subscribe (IN pal_upnp_cp_handle handle, IN const CHAR *event_url, INOUT INT32 *timeout, OUT pal_upnp_sid sid); -/************************************************************ - * Function: PAL_upnp_accept_subscription - * - * Parameters: - * handle: Input. The handle of the device. - * device_id: Input. The device ID of the subdevice of the - * service generating the event - * service_id: Input. The unique service identifier of the - * service generating the event. - * var_names: Input. Pointer to an array of event variables. - * var_vals: Input. Pointer to an array of values for - * the event variables. - * var_nb: Input. The number of event variables in var_names. - * sub_id: Input. The subscription ID of the newly - * registered control point. - * - * Description: - * This function accepts a subscription request and sends - * out the current state of the eventable variables for a service. - * The device application should call this function when it receives a - * UPNP_EVENT_SUBSCRIPTION_REQUEST callback. This function is sychronous - * and generates no callbacks. - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ +/** +* @brief Accept a subscription request and send initial event state. +* +* Accepts a subscription request and sends out the current state of the eventable variables for a service. +* \n The device application should call this function when it receives a UPNP_EVENT_SUBSCRIPTION_REQUEST callback. +* \n This function is synchronous and generates no callbacks. +* +* @param[in] handle - The handle of the device. +* @param[in] device_id - The device ID of the subdevice of the service generating the event. +* @param[in] service_id - The unique service identifier of the service generating the event. +* @param[in] var_names - Pointer to an array of event variable names. +* @param[in] var_vals - Pointer to an array of values for the event variables. +* @param[in] var_nb - The number of event variables in var_names. +* @param[in] sub_id - The subscription ID of the newly registered control point. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval Error code if acceptance fails. +*/ INT32 PAL_upnp_accept_subscription(IN pal_upnp_device_handle handle, IN const CHAR *device_id, IN const CHAR *service_id, @@ -594,32 +547,25 @@ INT32 PAL_upnp_accept_subscription(IN pal_upnp_device_handle handle, IN const CHAR **var_vals, IN INT32 var_nb, IN pal_upnp_sid sub_id); - -/************************************************************ - * Function: PAL_upnp_notify - * - * Parameters: - * handle: Input. The handle to the device sending the event. - * device_id: Input. The device ID of the subdevice of the - * service generating the event. - * service_name: Input. The unique identifier of the service - * generating the event. - * var_name: Input. Pointer to an array of variables that - * have changed. - * new_value: Input. Pointer to an array of new values for - * those variables. - * var_number: Input. The count of variables included in this - * notification. - * - * Description: - * This function sends out an event change notification to all - * control points subscribed to a particular service. This function is - * synchronous and generates no callbacks. - * - * Return Values: INT32 - * 0 if successful else error code. - ************************************************************/ + + /** +* @brief Send event change notification to subscribed control points. +* +* Sends out an event change notification to all control points subscribed to a particular service. +* \n This function is synchronous and generates no callbacks. +* +* @param[in] handle - The handle to the device sending the event. +* @param[in] device_id - The device ID of the subdevice of the service generating the event. +* @param[in] service_name - The unique identifier of the service generating the event. +* @param[in] var_name - Pointer to an array of variables that have changed. +* @param[in] new_value - Pointer to an array of new values for those variables. +* @param[in] var_number - The count of variables included in this notification. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval Error code if notification fails. +*/ INT32 PAL_upnp_notify (IN pal_upnp_device_handle handle, IN const CHAR *device_id, IN const CHAR *service_name, @@ -627,19 +573,17 @@ INT32 PAL_upnp_accept_subscription(IN pal_upnp_device_handle handle, IN const CHAR **new_value, IN INT32 var_number); -/************************************************************ - * Function: PAL_upnp_get_error_message - * - * Parameters: - * errno: Input, error code. - * - * Description: - * This functions returns the error string mapped to the error code. - * - * Return Values: const CHAR * - * return either the right string or "Unknown Error" - ************************************************************/ +/** +* @brief Get error message string for an error code. +* +* Returns the error string mapped to the specified UPnP error code. +* +* @param[in] errno - Error code. +* +* @return Error message string. +* @retval Error message string on success. +* @retval "Unknown Error" if error code is not recognized. +*/ const CHAR *PAL_upnp_get_error_message(IN INT32 errno); -#endif //__PAL_UPNP_H__ - +#endif //__PAL_UPNP_H__ \ No newline at end of file diff --git a/source/pal/upnp/include/pal_upnp_device.h b/source/pal/upnp/include/pal_upnp_device.h index d10f3629..8f5eac8c 100644 --- a/source/pal/upnp/include/pal_upnp_device.h +++ b/source/pal/upnp/include/pal_upnp_device.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -59,13 +59,13 @@ #define UDT_LNAME "UDT" -struct action_event +struct action_event { pal_upnp_action_request *request; struct upnp_service *service; }; -struct upnp_action +struct upnp_action { const CHAR *action_name; INT32 (*callback)(struct action_event *); @@ -77,7 +77,7 @@ struct upnp_variable CHAR value[PAL_UPNP_LINE_SIZE]; //state variable value }; -struct upnp_device +struct upnp_device { INT32 (*init_function)(VOID); //device init function INT32 (*destroy_function)(struct upnp_device *); //device destroy function @@ -86,7 +86,7 @@ struct upnp_device struct upnp_device *next; //UPnP device list }; -struct upnp_service +struct upnp_service { pthread_mutex_t service_mutex; //service mutex INT32 (*destroy_function)(struct upnp_service *); //service destroy function @@ -99,60 +99,60 @@ struct upnp_service }; -/************************************************************ - * Function: PAL_upnp_device_init - * - * Parameters: - * device: Input. upnp device pointer. - * ip_address: Input. Local IP Address. - * If input is NULL, an appropriate IP address will be automatically selected. - * port: Input . Local Port to listen for incoming connections. - * If input is NULL, a appropriate port will be automatically selected. - * timeout: Input. upnp device alive timeout value. - * desc_doc_name: Input. Device description file name. - * web_dir_path: Input. Local path for device description file. - * - * Description: - * This function initialize a upnp device. - * - * Return Values: INT32 - * 0 if successful else error code. More error code is TBD - ************************************************************/ -extern INT32 PAL_upnp_device_init(IN struct upnp_device *device, - IN CHAR *ip_address, - IN UINT32 port, +/** +* @brief Initialize a UPnP device. +* +* Initializes the UPnP device by calling the device's init function, +* \n initializing the UPnP library with the specified interface and port, +* \n registering the root device with the description file and web directory, +* \n and sending UPnP advertisements with the specified timeout. +* +* @param[in] device - UPnP device pointer. +* @param[in] ip_address - Local IP address or interface name. NULL for automatic selection. +* \n If ip_address is NULL, an appropriate IP address will be automatically selected. +* @param[in] port - Local port to listen for incoming connections. 0 for automatic selection. +* \n If port is 0, an appropriate port will be automatically selected. +* @param[in] timeout - UPnP device alive timeout value in seconds. 0 for default timeout. +* @param[in] desc_doc_name - Device description file name. +* \n Default value will be used if desc_doc_name is NULL. +* @param[in] web_dir_path - Local path for device description file. +* \n Default value will be used if web_dir_path is NULL. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval -1 if error (initialization failure, registration failure, or advertisement failure). +*/ +extern INT32 PAL_upnp_device_init(IN struct upnp_device *device, + IN CHAR *ip_address, + IN UINT32 port, IN UINT32 timeout, IN const CHAR *desc_doc_name, IN const CHAR *web_dir_path); -/************************************************************ - * Function: PAL_upnp_device_destroy - * - * Parameters: - * device: Input. upnp device pointer. - * - * Description: - * This function destroy a upnp device. - * - * Return Values: INT32 - * 0 if successful else error code. More error code is TBD - ************************************************************/ +/** +* @brief Destroy a UPnP device. +* +* Destroys the UPnP device by calling the destroy function for the device and all linked devices, +* \n unregistering the root device from the UPnP library, and cleaning up UPnP resources. +* \n Resets the device handle and initialization status. +* +* @param[in] device - UPnP device pointer. +* +* @return The status of the operation. +* @retval 0 if successful. +*/ extern INT32 PAL_upnp_device_destroy(IN struct upnp_device *device); -/************************************************************ - * Function: PAL_upnp_device_getHandle - * - * Parameters: - * None. - * - * Description: - * This function get device handle. - * - * Return Values: pal_upnp_device_handle - * device handle - ************************************************************/ +/** +* @brief Get the UPnP device handle. +* +* Returns the device handle assigned during device initialization. +* \n This handle is used for UPnP operations such as sending notifications. +* +* @return The UPnP device handle. +*/ extern pal_upnp_device_handle PAL_upnp_device_getHandle(VOID); diff --git a/source/pal/xml/include/pal_xml.h b/source/pal/xml/include/pal_xml.h index 8dbdb8b0..f3bca6f0 100644 --- a/source/pal/xml/include/pal_xml.h +++ b/source/pal/xml/include/pal_xml.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -50,7 +50,7 @@ * * **/ - + #ifndef __PAL_XML_H__ #define __PAL_XML_H__ @@ -81,347 +81,299 @@ typedef struct{ CHAR *tag_name; }pal_xml_element; -/************************************************************ - * Function: PAL_xml_nodelist_GetbyName - * - * Parameters: - * top: Input. Search elemenets from this top tree. - * name: Input. Search target name of tag. - * ns_url: Input. Search the tag with name space url. - * - * Description: - * Returns a nodeList of all the descendant Elements with a given - * name and namespace in the order in which they are encountered - * in a preorder traversal of the element tree. - * - * Return Values: pal_xml_nodelist * - * return all matched elemenets list, NULL if nothing found. - ************************************************************/ +/** + * @brief Get a node list of all descendant elements with a given name and namespace. + * + * Returns a nodeList of all the descendant Elements with a given name and namespace in the order + * in which they are encountered in a preorder traversal of the element tree. + * + * @param[in] top - The XML top tree to search elements from + * @param[in] name - The target tag name to search for + * @param[in] ns_url - The namespace URL of the tag to search for + * + * @return Pointer to pal_xml_nodelist containing all matched elements + * @retval Non-NULL - A list of all matched elements + * @retval NULL - No matching elements found + */ pal_xml_nodelist *PAL_xml_nodelist_GetbyName(IN pal_xml_top *top, IN const CHAR *name, IN const CHAR *ns_url); - -/************************************************************ - * Function: PAL_xml_node_GetFirstbyName - * - * Parameters: - * top: Input. Search the tag from this top tree. - * name: Input. Search target name of tag. - * ns_url: Input. Search the tag with name space url. - * - * Description: - * Returns the first node matched the given name and namespace. - * - * Return Values: pal_xml_node * - * return the matched elemenet node, NULL if nothing found. - ************************************************************/ +/** + * @brief Get the first node matching the given name and namespace. + * + * Returns the first node that matches the given name and namespace from the XML tree. + * + * @param[in] top - The XML top tree to search from + * @param[in] name - The target tag name to search for + * @param[in] ns_url - The namespace URL of the tag to search for + * + * @return Pointer to the matched element node + * @retval Non-NULL - The first matched element node + * @retval NULL - No matching element found + */ pal_xml_node *PAL_xml_node_GetFirstbyName(IN pal_xml_top *top, IN const CHAR *name, IN const CHAR *ns_url); - -/************************************************************ - * Function: PAL_xml_nodelist_item - * - * Parameters: - * list: Input. To get node from this list. - * index: Input. Need to get the indexth node. - * - * Description: - * Returns the indexth item in the collection. If index is greater -* than or equal to the number of nodes in the list, this returns -* null. - * - * Return Values: pal_xml_node * - * return the matched elemenet node, NULL if nothing found. - ************************************************************/ +/** + * @brief Get the node at the specified index in the node list. + * + * Returns the indexth item in the collection. If index is greater than or equal to the number + * of nodes in the list, this returns NULL. + * + * @param[in] list - The node list to get the node from + * @param[in] index - The index of the node to retrieve (zero-based) + * + * @return Pointer to the element node at the specified index + * @retval Non-NULL - The matched element node at the given index + * @retval NULL - Index out of range or list is empty + */ pal_xml_node *PAL_xml_nodelist_item (IN pal_xml_nodelist *list, IN ULONG index); - -/************************************************************ - * Function: PAL_xml_node_GetFirstChild +/** + * @brief Get the first child node of the specified parent node. + * + * Returns the first child of the given node. * - * Parameters: - * node: Input. As the parent node. - * - * Description: - * Returns the first child of node. - * - * Return Values: pal_xml_node * - * return the matched elemenet node, NULL if nothing found. - ************************************************************/ + * @param[in] node - The parent node + * + * @return Pointer to the first child element node + * @retval Non-NULL - The first child element node + * @retval NULL - Node has no children + */ pal_xml_node *PAL_xml_node_GetFirstChild(IN pal_xml_node *node); - -/************************************************************ - * Function: PAL_xml_node_get_value +/** + * @brief Get the text value of the specified node. * - * Parameters: - * node: Input. The node to get value. - * - * Description: - * Returns the value of node. - * - * Return Values: CHAR * - * return string value of the elemenet, NULL if nothing found. - ************************************************************/ + * Returns the value of the node by retrieving the text content from its first child text node. + * + * @param[in] node - The node to get the value from + * + * @return String value of the element + * @retval Non-NULL - The text value of the element node + * @retval NULL - Node has no value or is invalid + */ CHAR *PAL_xml_node_get_value(IN pal_xml_node *node); - -/************************************************************ - * Function: PAL_xml_nodelist_free +/** + * @brief Free a node list and release its resources. + * + * Frees the memory allocated for a pal_xml_nodelist structure. + * + * @param[in] list - The node list to be freed * - * Parameters: - * list: Input. The list to be freed. - * - * Description: - * Free a pal_node_list. - * - * Return Values: VOID - * - ************************************************************/ + * @return None + */ VOID PAL_xml_nodelist_free(IN pal_xml_nodelist *list); - - -/************************************************************ - * Function: PAL_xml_parse_buffer +/** + * @brief Parse an XML document from a buffer. + * + * Parses the XML content stored in the buffer and creates a document tree structure. + * + * @param[in] buffer - The buffer containing the XML document content * - * Parameters: - * buffer: Input. The buffer stores XML file. - * - * Description: - * Parse xml file stored in buffer. - * - * Return Values: pal_xml_top * - * return parsed tree. NULL if fail. - ************************************************************/ + * @return Pointer to the parsed XML document tree + * @retval Non-NULL - Successfully parsed XML document tree + * @retval NULL - Parsing failed or invalid buffer + */ pal_xml_top *PAL_xml_parse_buffer(IN const CHAR *buffer); - -/************************************************************ - * Function: PAL_xml_nodelist_length +/** + * @brief Get the number of nodes in the node list. + * + * Returns the number of nodes in the list. The range of valid child node indices is 0 to length-1 inclusive. + * + * @param[in] list - The node list to query * - * Parameters: - * list: Input. pal node list. - * - * Description: - * Returns the number of nodes in the list. The range of valid - * child node indices is 0 to length-1 inclusive. - * - * Return Values: ULONG - * Returns the number of nodes in the list. - ************************************************************/ + * @return The number of nodes in the list + */ ULONG PAL_xml_nodelist_length(IN pal_xml_nodelist *list); - -/************************************************************ - * Function: PAL_xml_top_free +/** + * @brief Free the XML document tree and release its resources. + * + * Frees the memory allocated for the XML document tree. * - * Parameters: - * top: Input. The top tree to be freed. - * - * Description: - * Free the top tree. - * - * Return Values: VOID - ************************************************************/ + * @param[in] top - The XML document tree to be freed + * + * @return None + */ VOID PAL_xml_top_free(IN pal_xml_top *top); - -/************************************************************ - * Function: PAL_xml_node_print +/** + * @brief Print the DOM tree under the specified node. + * + * Converts the DOM tree structure under the given node to a formatted XML string representation + * with whitespace formatting for readability. + * + * @param[in] node - The node to be printed * - * Parameters: - * node: Input. The node to be printed. - * - * Description: - * Print DOM tree under node. Puts lots of white spaces - * - * Return Values: CHAR * - * return a string pointed to parsed result. - ************************************************************/ + * @return Pointer to a string containing the formatted XML representation + * @retval Non-NULL - A string containing the formatted XML tree + * @retval NULL - Printing failed or invalid node + */ CHAR *PAL_xml_node_print(IN pal_xml_node *node); - -/************************************************************ - * Function: PAL_xml_top_print +/** + * @brief Print the entire XML document with XML prolog. + * + * Prints the entire XML document, prepending the XML prolog first, with whitespace formatting + * for readability. + * + * @param[in] top - The XML document tree to be printed * - * Parameters: - * top: Input. The top tree to be printed. - * - * Description: - * Prints entire document, prepending XML prolog first. - * Puts lots of white spaces. - * - * Return Values: CHAR * - * return a string pointed to parsed result. - ************************************************************/ + * @return Pointer to a string containing the formatted XML document + * @retval Non-NULL - A string containing the complete formatted XML document with prolog + * @retval NULL - Printing failed or invalid document + */ CHAR *PAL_xml_top_print(IN pal_xml_top *top); - -/************************************************************ - * Function: PAL_xml_top_creat +/** + * @brief Create a new XML document object. + * + * Creates a new XML document tree object with the nodeName set to "#document". * - * Parameters: - * N/A - * - * Description: - * Creates an xml top object. - * - * Return Values: pal_xml_top * - * A new top object with the nodeName set to "#document". - ************************************************************/ + * @return Pointer to the newly created XML document object + * @retval Non-NULL - A new XML document object + * @retval NULL - Creation failed + */ pal_xml_top *PAL_xml_top_creat(); - -/************************************************************ - * Function: PAL_xml_create_element - * - * Parameters: - * top: Input. The xml top related to the element. - * namespace: Input. the namespace URI of the element to create. - * node_name: Input. the qualified name of the element to instantiate. - * - * Description: - * Creates an xml top object. - * - * Return Values: pal_xml_element * - * The new element object created. - ************************************************************/ +/** + * @brief Create a new XML element with optional namespace. + * + * Creates a new XML element node with the specified tag name and optional namespace URI. If namespace + * is provided, creates a namespaced element; otherwise creates a standard element. + * + * @param[in] top - The XML document object related to the element + * @param[in] tag_name - The qualified name of the element to instantiate + * @param[in] namespace - The namespace URI of the element to create + * + * @return Pointer to the newly created element object + * @retval Non-NULL - The new element object successfully created + * @retval NULL - Creation failed or invalid parameters + */ pal_xml_element *PAL_xml_element_create (IN pal_xml_top * top, IN const CHAR* tag_name, IN const CHAR* namespace); - -/************************************************************ - * Function: PAL_xml_element_set_attr - * - * Parameters: - * element: Input. The xml element. - * name: Input. The name of the attribute to create or alter. - * value: Input. Value to set in string form - * - * Description: - * Adds a new attribute. If an attribute with that name is already - * present in the element, its value is changed to be that of the value - * parameter. If not, a new attribute is inserted into the element. - * - * Return Values: INT32 - * 0 or failure code. - ************************************************************/ +/** + * @brief Set or update an attribute on an XML element. + * + * Adds a new attribute to the element. If an attribute with that name is already present in the element, + * its value is changed to be that of the value parameter. If not, a new attribute is inserted into the element. + * + * @param[in] element - The XML element to modify + * @param[in] name - The name of the attribute to create or alter + * @param[in] value - The value to set in string form + * + * @return The status of the operation + * @retval 0 - Success + * @retval Non-zero - Failure code + */ INT32 PAL_xml_element_set_attr(IN pal_xml_element *element, IN const CHAR *name, IN const CHAR *value); - -/************************************************************ - * Function: PAL_xml_node_append_child - * - * Parameters: - * node: Input. The node as parent. - * newChild: Input. the node to add as child. - * - * Description: - * Adds the node newChild to the end of the list of children of this node. - * If the newChild is already in the tree, it is first removed. - * - * Return Values: INT32 - * 0 or failure code. - ************************************************************/ +/** + * @brief Append a child node to a parent node. + * + * Adds the node newChild to the end of the list of children of the parent node. If the newChild is + * already in the tree, it is first removed before being appended. + * + * @param[in] node - The parent node + * @param[in] newChild - The child node to add + * + * @return The status of the operation + * @retval 0 - Success + * @retval Non-zero - Failure code + */ INT32 PAL_xml_node_append_child(IN pal_xml_node * node, IN pal_xml_node * newChild); - -/************************************************************ - * Function: PAL_xml_top_AddElementTextValue - * - * Parameters: - * top: Input. Related xml top. - * parent: Input. The element to be changed. - * tag_name: Input. The sub element to be added. - * value: Input. text value of the node. - * Description: - * Add a sub element with only text value. - * - * Return Values: VOID - * - ************************************************************/ - VOID PAL_xml_top_AddElementTextValue(IN pal_xml_top *top, - IN pal_xml_element *parent, - IN CHAR *tag_name, +/** + * @brief Add a child element with text value to a parent element. + * + * Creates a new child element with the specified tag name, sets its text content to the provided value, + * and appends it to the parent element. + * + * @param[in] top - The related XML document object + * @param[in] parent - The parent element to which the child will be added + * @param[in] tag_name - The tag name of the child element to be added + * @param[in] value - The text value of the child element + * + * @return None + */ + VOID PAL_xml_top_AddElementTextValue(IN pal_xml_top *top, + IN pal_xml_element *parent, + IN CHAR *tag_name, IN CHAR *value); - -/************************************************************ - * Function: PAL_xml_top_AddElementIntValue - * - * Parameters: - * top: Input. Related xml top. - * parent: Input. The element to be changed. - * tag_name: Input. The sub element to be added. - * value: Input. INT32 value of the node. - * Description: - * Add a sub element with INT32 value. - * - * Return Values: VOID - * - ************************************************************/ - VOID PAL_xml_top_AddElementIntValue(IN pal_xml_top *top, - IN pal_xml_element *parent, - IN CHAR *tagname, +/** + * @brief Add a child element with INT32 value to a parent element. + * + * Creates a new child element with the specified tag name, converts the INT32 value to string format, + * and appends it to the parent element. + * + * @param[in] top - The related XML document object + * @param[in] parent - The parent element to which the child will be added + * @param[in] tagname - The tag name of the child element to be added + * @param[in] value - The INT32 value of the child element + * + * @return None + */ + VOID PAL_xml_top_AddElementIntValue(IN pal_xml_top *top, + IN pal_xml_element *parent, + IN CHAR *tagname, IN INT32 value); - -/************************************************************ - * Function: PAL_xml_top_AddElementLongValue - * - * Parameters: - * top: Input. Related xml top. - * parent: Input. The element to be changed. - * tag_name: Input. The sub element to be added. - * value: Input. long value of the node. - * Description: - * Add a sub element with INT32 value. - * - * Return Values: VOID - * - ************************************************************/ - VOID PAL_xml_top_AddElementLongValue(IN pal_xml_top *top, - IN pal_xml_element *parent, - IN CHAR *tagname, +/** + * @brief Add a child element with long long value to a parent element. + * + * Creates a new child element with the specified tag name, converts the long long value to string format, + * and appends it to the parent element. + * + * @param[in] top - The related XML document object + * @param[in] parent - The parent element to which the child will be added + * @param[in] tagname - The tag name of the child element to be added + * @param[in] value - The long long value of the child element + * + * @return None + */ + VOID PAL_xml_top_AddElementLongValue(IN pal_xml_top *top, + IN pal_xml_element *parent, + IN CHAR *tagname, IN long long value); - -/************************************************************ - * Function: PAL_xml_top_create_textnode +/** + * @brief Create a text node with the specified content. + * + * Creates a new text node with the provided text data, which is stored in the nodeValue field. * - * Parameters: - * top: Input. Related xml top. - * data: text data for the text node. It is stored in nodeValue field. - * Description: - * Creates an text node. - * - * Return Values: pal_xml_node * - * The new text node. - ************************************************************/ + * @param[in] top - The related XML document object + * @param[in] data - The text data for the text node + * + * @return Pointer to the newly created text node + * @retval Non-NULL - The new text node successfully created + * @retval NULL - Creation failed + */ pal_xml_node *PAL_xml_top_create_textnode(IN pal_xml_top * top, IN const CHAR *data); - -/************************************************************ - * Function: PAL_xml_escape +/** + * @brief Escape special XML characters in a string. * - * Parameters: - * src_str: Input. Src string. - * attribute: Input. This string is attribute or not. - * Description: - * Escape the a src XML string to a normal string. - * - * Return Values: CHAR * - * Return the result escaped string. - ************************************************************/ + * Converts special XML characters in the source string to their corresponding + * XML entity representations. The conversion depends on whether the string is used as an attribute value. + * + * @param[in] src_str - The source string to be escaped + * @param[in] attribute - Flag indicating whether this string is an attribute value (TRUE) or element content (FALSE) + * + * @return Pointer to the escaped string + * @retval Non-NULL - The result escaped string with XML entities + * @retval NULL - Escape operation failed + */ CHAR *PAL_xml_escape(IN const CHAR *src_str, IN BOOL attribute); - - -#endif //__PAL_XML_H__ +#endif //__PAL_XML_H__ \ No newline at end of file diff --git a/source/pal/xml/include/pal_xml2s.h b/source/pal/xml/include/pal_xml2s.h index b1c1f103..261af8ab 100644 --- a/source/pal/xml/include/pal_xml2s.h +++ b/source/pal/xml/include/pal_xml2s.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -50,7 +50,7 @@ * * **/ - + #ifndef __PAL_XML2S_H__ #define __PAL_XML2S_H__ @@ -86,14 +86,14 @@ typedef ULONG PAL_XML2S_FDMSK; #define XML2S_TABLE_END {NULL, 0, 0, NULL, 0} -#define PAL_XML2S_INT8 1 +#define PAL_XML2S_INT8 1 #define PAL_XML2S_INT16 2 #define PAL_XML2S_INT32 3 #define PAL_XML2S_UINT8 4 #define PAL_XML2S_UINT16 5 #define PAL_XML2S_UINT32 6 -#define PAL_XML2S_STRING 7 -#define PAL_XML2S_STRUCT 8 +#define PAL_XML2S_STRING 7 +#define PAL_XML2S_STRUCT 8 #define PAL_XML2S_MAX_BITS 0xFFFF #define PAL_XML2S_ARRAY (0x0001 << 16) //array @@ -103,54 +103,54 @@ typedef ULONG PAL_XML2S_FDMSK; typedef struct _pal_xml2s_table{ CHAR *tag_name; //got the node from xml dom tree by given name - - UINT32 type; //the content type of the element - UINT32 offset; //member offset in a struct -- + UINT32 type; //the content type of the element + + UINT32 offset; //member offset in a struct -- //#define offsetof(s,m) (size_t)&(((s *)0)->m) struct _pal_xml2s_table *child_s; //point to the child sturcture member (array also taken as a common structure) UINT32 mask_bit; /*mask the sturcture's fieldmask once find the element - * NOTE: For a structure array, this field must be the size of the structure. + * NOTE: For a structure array, this field must be the size of the structure. */ }PAL_XML2S_TABLE; -/************************************************************ - * Function: PAL_xml2s_process +/** + * @brief Translate an XML tree to a data structure according to translation rules. * - * Parameters: - * xml: Input. the xml dom tree(node) to be translated - * trans_table: Input. the translate table - * data_buff: InputOutput. Data structure memory buffer. - * - * Description: - * Translate the xml tree to a given data sturct according to the rules - * in translate table. - * - * - * Return Values: INT32 - * 0 if sucessful, otherwise return error code. - ************************************************************/ - INT32 PAL_xml2s_process(IN pal_xml_top *xml, - IN PAL_XML2S_TABLE *trans_table, + * Translates the XML DOM tree to a given data structure according to the rules defined in the + * translation table. The function processes both simple types and complex structures, including arrays. It recursively handles nested structures + * and allocates memory for dynamic arrays. The data buffer must be pre-allocated by the caller. + * + * @param[in] xml - The XML DOM tree (node) to be translated + * @param[in] trans_table - The translation table defining the mapping rules between XML elements and data structure fields + * @param[in,out] data_buff - Data structure memory buffer where the translated data will be stored + * + * @return The status of the operation + * @retval PAL_XML2S_E_SUCCESS (0) - Translation successful + * @retval PAL_XML2S_E_INVALID_ARG (-1) - Invalid arguments provided + * @retval PAL_XML2S_E_OUTOF_MEM (-2) - Out of memory during array allocation + * @retval PAL_XML2S_E_TAG_MISSING (-3) - Required XML tag missing + * @retval PAL_XML2S_E_FORMAT (-4) - Format error during translation + */ + INT32 PAL_xml2s_process(IN pal_xml_top *xml, + IN PAL_XML2S_TABLE *trans_table, INOUT VOID *data_buff); -/************************************************************ - * Function: PAL_xml2s_free +/** + * @brief Free all memory allocated during XML to structure translation. + * + * Frees all memory allocated during PAL_xml2s_process, including dynamically allocated arrays and strings. + * The data_buff must have been populated by PAL_xml2s_process using the same translation table to ensure + * proper memory deallocation. The function recursively frees nested structures and array elements. * - * Parameters: - * data_buff: Input. The buffer to be freed. - * trans_table: The rule table for the free. - * Description: - * free all the memroy allocated during PAL_xml2s_process. - * The data_buff must be got from PAL_xml2s_process with the same rule table. - * - * Return Values: VOID - * - ************************************************************/ + * @param[in] data_buff - The data buffer to be freed, obtained from PAL_xml2s_process + * @param[in] trans_table - The translation table used during PAL_xml2s_process + * + * @return None + */ VOID PAL_xml2s_free(IN VOID *data_buff, IN PAL_XML2S_TABLE *trans_table); - #endif //__PAL_XML2S_H__ diff --git a/source/scripts/init/src/apply_system_defaults_helper.h b/source/scripts/init/src/apply_system_defaults_helper.h index 4be5bc15..cae3e53e 100644 --- a/source/scripts/init/src/apply_system_defaults_helper.h +++ b/source/scripts/init/src/apply_system_defaults_helper.h @@ -22,31 +22,232 @@ * * Licensed under the Apache License, Version 2.0 (the "License"); **********************************************************************/ -#ifndef _APPLY_SYSTEM_DEFAULTS_HELPER_H_ +#ifndef _APPLY_SYSTEM_DEFAULTS_HELPER_H_ #define _APPLY_SYSTEM_DEFAULTS_HELPER_H_ #define APPLY_DEFAULTS_FACTORY_RESET "/tmp/.apply_defaults_factory_reset" #if defined (_RDKB_GLOBAL_PRODUCT_REQ_) #define PARTNER_ID_MAX_RETRY 5 + +/** +* @brief Fetch Partner ID with retry mechanism. +* +* Attempts to fetch the Partner ID from factory HAL or device properties with multiple retries. +* \n Validates the Partner ID and ensures it is not "Unknown". +* \n Maximum retry count is PARTNER_ID_MAX_RETRY. +* \n The buffer pointed by PartnerID should be allocated with a size of at least PARTNER_ID_LEN bytes. +* +* @param[out] PartnerID - Buffer to store the fetched Partner ID. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval 1 if failed after all retries. +*/ int PartnerId_FetchWithRetry(char *PartnerID ); + +/** +* @brief Write Partner ID to file. +* +* Writes the Partner ID string to the /nvram/.partner_ID file. +* +* @param[in] PartnerID - Partner ID string to write to file. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval 1 if error (file open failure or NULL Partner ID). +*/ int WritePartnerIDToFile(char* PartnerID); + +/** +* @brief Check and handle invalid Partner ID recovery process. +* +* Detects invalid or "Unknown" Partner ID values and triggers recovery process. +* \n Retries fetching valid Partner ID, updates syscfg, triggers factory reset if needed, +* \n and creates /nvram/.Invalid_PartnerID file for tracking. +* +* @param[in,out] PartnerID - Partner ID buffer to validate and potentially update. +* +* @return None +*/ void CheckAndHandleInvalidPartnerIDRecoveryProcess(char *PartnerID); + #endif // (_RDKB_GLOBAL_PRODUCT_REQ_) +/** +* @brief Get the Partner ID. +* +* Retrieves Partner ID from /nvram/.partner_ID file if available, +* \n otherwise fetches from factory HAL or device.properties file. +* \n Falls back to platform-specific defaults if all sources fail. +* \n The buffer pointed by PartnerID should be allocated with a size of at least PARTNER_ID_LEN bytes. +* +* @param[out] PartnerID - Buffer to store the retrieved Partner ID. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval Non-zero if error. +*/ int get_PartnerID( char *PartnerID); + +/** +* @brief Get factory Partner ID from HAL. +* +* Retrieves the factory Partner ID from platform HAL with retry mechanism (3 attempts). +* +* @param[out] pValue - Buffer to store the factory Partner ID. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval -1 if failed after all retries or not supported. +*/ int getFactoryPartnerId (char *pValue); + +/** +* @brief Parse command line arguments. +* +* Parses command line options, if any command line args then apply them. +* +* @param[in] argc - Argument count. +* @param[in] argv - Argument vector array. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval -1 if error. +*/ int parse_command_line(int argc, char **argv); + +/** +* @brief Set system default values. +* +* Applies system defaults by setting syscfg and sysevent variables. +* \n Processes syscfg variables first, then sysevent variables. +* \n Checks version compatibility before applying defaults. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval -1 if error. +*/ int set_defaults(void); + +/** +* @brief Set syscfg partner values. +* +* Sets and commits a syscfg parameter with the specified value for partner-specific configuration. +* +* @param[in] pValue - Value to set for the parameter. +* @param[in] param - Parameter name to set in syscfg. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval 1 if syscfg_set_commit failed. +*/ int set_syscfg_partner_values (char *pValue, char *param); + +/** +* @brief Compare partner JSON parameters. +* +* Compares partner parameters between bootstrap.json (NVRAM) and partners_defaults.json (etc). +* \n Removes unknown objects from bootstrap.json and validates Partner ID. +* \n Reinitializes bootstrap.json if parsing errors occur. +* +* @param[in] partner_nvram_bs_obj - JSON string from bootstrap.json. +* @param[in] partner_etc_obj - JSON string from partners_defaults.json. +* @param[in] PartnerID - Partner ID to validate. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval -1 if JSON parse error or reinitialization needed. +*/ int compare_partner_json_param (char *partner_nvram_bs_obj, char *partner_etc_obj, char *PartnerID); + +/** +* @brief Apply Partner ID specific default values. +* +* Applies partner-specific default values from JSON configuration. +* \n Handles syscfg and PSM parameter updates based on partner configuration. +* \n Checks /nvram/.apply_partner_defaults file to determine if defaults need to be applied. +* +* @param[in] data - JSON configuration data string. +* @param[in] PartnerID - Partner ID for which to apply defaults. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval Non-zero if error. +*/ int apply_partnerId_default_values (char *data, char *PartnerID); + +/** +* @brief Parse JSON file. +* +* Reads and loads a JSON file from the specified path into memory. +* \n Allocates memory for the file content which must be freed by the caller. +* +* @param[in] path - File path of the JSON file to parse. +* +* @return Pointer to allocates json string. +* @retval Pointer to allocated JSON string on success. +* @retval NULL on failure. +*/ char *json_file_parse (char *path); + +/** +* @brief Initialize bootstrap JSON file. +* +* Creates or updates bootstrap.json by merging partner NVRAM and etc configurations. +* \n Adds properties, default values, active values, and update timestamps. +* \n Handles model-specific overrides and writes to /opt/secure/bootstrap.json. +* +* @param[in] partner_nvram_obj - JSON string from NVRAM partner configuration. +* @param[in] partner_etc_obj - JSON string from etc partner configuration. +* @param[in] PartnerID - Partner ID for which to initialize bootstrap. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval Non-zero if error. +*/ int init_bootstrap_json (char *partner_nvram_obj, char *partner_etc_obj, char *PartnerID); + +/** +* @brief Get Partner ID with retry mechanism. +* +* Attempts to retrieve Partner ID from syscfg.db with retries (up to RETRY_COUNT attempts). +* \n Falls back to factory Partner ID if syscfg retrieval fails after all retries. +* \n The buffer pointed by buf and PartnerID should be allocated with at least 64 bytes. +* +* @param[out] buf - Temporary buffer for syscfg retrieval. +* @param[out] PartnerID - Buffer to store the retrieved Partner ID. +* +* @return None +*/ void getPartnerIdWithRetry(char* buf, char* PartnerID); -/* Function - dbus initialization */ + +/** +* @brief Initialize D-Bus connection. +* +* Initializes the CCSP message bus connection for D-Bus communication. +* \n Uses either synchronous or asynchronous initialization based on DBUS_INIT_SYNC_MODE. +* \n Sets up the global bus handle for subsequent D-Bus operations. +* +* @return The status of the operation. +* @retval 0 or positive value if successful. +* @retval -1 if initialization failed. +*/ int dbusInit(void); -/* Function - PSM SET API*/ + +/** +* @brief Set PSM record value. +* +* Sets a PSM (Persistent Storage Manager) record with the specified name and value. +* \n Includes retry mechanism to handle PSM initialization delays during early bootup. +* +* @param[in] name - Name of the PSM record. +* @param[in] str - Value to set for the PSM record. +* +* @return The status of the operation. +* @retval CCSP_SUCCESS if successful. +* @retval Error code if failed after all retries. +*/ int set_psm_record(char *name,char *str); #endif /* _APPLY_SYSTEM_DEFAULTS_HELPER_H_ */ diff --git a/source/service_dhcp/include/dhcp_server_functions.h b/source/service_dhcp/include/dhcp_server_functions.h index c3b91d58..83ca921c 100644 --- a/source/service_dhcp/include/dhcp_server_functions.h +++ b/source/service_dhcp/include/dhcp_server_functions.h @@ -19,15 +19,143 @@ #ifndef _DHCP_SERVER_FUNCTIONS_H #define _DHCP_SERVER_FUNCTIONS_H + +/** +* @brief Prepare hostname configuration. +* +* Sets the system hostname from syscfg and creates /etc/hosts and /etc/hostname files. +* \n Writes hostname, localhost entries, and IPv6 entries to hosts file. +* \n Handles SecureWebUI LocalFqdn configuration if enabled. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval Non-zero if error. +*/ int prepare_hostname(); + +/** +* @brief Calculate and write DHCP range configuration. +* +* Calculates DHCP IP address range based on LAN IP address and netmask. +* \n Writes dhcp-range configuration to the dnsmasq configuration file. +* \n Includes lease time and DHCP start/end addresses. +* +* @param[in] local_dhcpconf_file - File pointer to dnsmasq configuration file. +* @param[in] prefix - Prefix string for DHCP configuration (typically interface name). +* +* @return None +*/ void calculate_dhcp_range (FILE *local_dhcpconf_file, char *prefix); + +/** +* @brief Prepare DHCP static hosts configuration. +* +* Reads static host entries from syscfg and writes them to /etc/dhcp_static_hosts +* \n file with MAC address, IP address, and lease time. +* +* @return None +*/ void prepare_dhcp_conf_static_hosts(); + +/** +* @brief Prepare DHCP options for WAN DNS propagation. +* +* Writes DNS server options to /etc/dhcp_options file if dhcp_server_propagate_wan_nameserver is enabled. +* \n Retrieves WAN DHCP DNS servers from sysevent and formats them as dnsmasq options. +* +* @return None +*/ void prepare_dhcp_options_wan_dns(); + +/** +* @brief Prepare whitelist URLs for captive portal mode. +* +* Adds address and server entries to dnsmasq configuration for whitelisted URLs +* \n used in captive portal mode, including redirect URLs and cloud personal URLs. +* \n Resolves URLs to IP addresses using erouter0 interface. +* +* @param[in] fp_local_dhcp_conf - File pointer to dnsmasq configuration file. +* +* @return None +*/ void prepare_whitelist_urls(FILE *); + +/** +* @brief Configure extra DHCP pools. +* +* Iterates through configured DHCP pools and adds dhcp-range entries to dnsmasq configuration. +* \n Handles pool-specific options including DNS nameservers and lease times. +* \n Supports multiple network interfaces and pool configurations. +* +* @param[in] local_dhcpconf_file - File pointer to dnsmasq configuration file. +* @param[in] prefix - Prefix string for DHCP configuration. +* @param[in] bDhcpNs_Enabled - Flag indicating if DHCP nameserver is enabled. +* @param[in] pWan_Dhcp_Dns - WAN DHCP DNS server string. +* +* @return None +*/ void do_extra_pools (FILE *local_dhcpconf_file, char *prefix, unsigned char bDhcpNs_Enabled, char *pWan_Dhcp_Dns); + +/** +* @brief Prepare complete DHCP server configuration. +* +* Main function that generates the dnsmasq configuration file /var/dnsmasq.conf. +* \n Configures DHCP ranges, static hosts, DNS options, extra pools, and interface bindings. +* \n Handles captive portal mode, IoT network, and various platform-specific configurations. +* \n Creates necessary directories and copies configuration files to appropriate locations. +* +* @return The status of the operation. +* @retval 0 if successful. +* @retval Non-zero if error. +*/ int prepare_dhcp_conf(); + +/** +* @brief Check and retrieve WAN DHCP DNS servers. +* +* Retrieves wan_dhcp_dns from sysevent and converts space-separated DNS addresses +* \n to comma-separated format for dnsmasq configuration. +* \n The buffer pointed by pl_cWan_Dhcp_Dns should be allocated with at least 256 bytes. +* +* @param[out] pl_cWan_Dhcp_Dns - Buffer to store comma-separated WAN DHCP DNS addresses. +* +* @return None +*/ void check_and_get_wan_dhcp_dns( char *pl_cWan_Dhcp_Dns ); + +/** +* @brief Get DHCP options for brlan0 interface. +* +* Constructs dhcp-option string for brlan0 with DNS nameservers from syscfg. +* \n Includes dhcp_nameserver_1, dhcp_nameserver_2, dhcp_nameserver_3, and WAN DNS if SecureWebUI is enabled. +* \n The buffer pointed by pDhcpNs_OptionString should be allocated with at least 1024 bytes. +* +* @param[out] pDhcpNs_OptionString - Buffer to store formatted DHCP option string. +* +* @return None +*/ void get_dhcp_option_for_brlan0( char *pDhcpNs_OptionString ); + +/** +* @brief Prepare static DNS URL entries. +* +* Reads static DNS URLs from /etc/dns_static_urls file and adds server entries +* \n to dnsmasq configuration for blocking or redirecting specific domains. +* +* @param[in] fp_local_dhcp_conf - File pointer to dnsmasq configuration file. +* +* @return None +*/ void prepare_static_dns_urls(FILE *fp_local_dhcp_conf); + +/** +* @brief Update DHCP configuration based on sysevent change. +* +* Monitors dhcp_conf_change sysevent and updates internal configuration list. +* \n Handles interface additions, updates with different ranges, and removals. +* \n Maintains dynamic DHCP configuration for multiple interfaces. +* +* @return None +*/ void UpdateDhcpConfChangeBasedOnEvent(); -#endif /* _DHCP_SERVER_FUNCTIONS_H */ +#endif /* _DHCP_SERVER_FUNCTIONS_H */ \ No newline at end of file diff --git a/source/service_dhcp/include/lan_handler.h b/source/service_dhcp/include/lan_handler.h index 6816b2f2..a0f4174f 100644 --- a/source/service_dhcp/include/lan_handler.h +++ b/source/service_dhcp/include/lan_handler.h @@ -29,11 +29,112 @@ extern void* g_vBus_handle; #define PSM_VALUE_SET_STRING(name, str) PSM_Set_Record_Value2(g_vBus_handle, CCSP_SUBSYS, name, ccsp_string, str) #define PSM_VALUE_GET_INS(name, pIns, ppInsArry) PsmGetNextLevelInstances(g_vBus_handle, CCSP_SUBSYS, name, pIns, ppInsArry) +/** + * @brief Initialize and bring up the LAN interface. + * + * Initializes the primary LAN interface by retrieving configuration from PSM (Persistent Storage Manager), + * setting up L2 and L3 network instances, configuring bridge ports, and establishing the LAN network. + * The function handles home security network setup, manages async event handlers, and triggers the + * necessary system events to bring the LAN interface operational. It also handles multi-LAN feature + * enablement and logs boot-up timing information. + * + * @return None + */ void bring_lan_up(); -void ipv4_status(int, char *); + +/** + * @brief Update the IPv4 status for a specified L3 instance. + * + * Handles the IPv4 status changes (up/down) for a given L3 network instance. When status is "up", + * it configures the interface with IPv4 and IPv6 addresses, enables DHCP server, sets up firewall rules, + * and manages various network services. When status is "down", it tears down the network configuration. + * The function also handles erouter mode changes, DS-Lite configuration, IPv6 prefix delegation, and + * bridge mode transitions. + * + * @param[in] l3_inst - The L3 network instance number + * @param[in] status - The IPv4 status string ("up" or "down") + * + * @return None + */ +void ipv4_status(int l3_inst, char *status); + +/** + * @brief Restart the LAN interface with updated configuration. + * + * Restarts the LAN interface by comparing current syscfg values with PSM stored values for IP address + * and subnet mask. If changes are detected, it updates the PSM, flushes IPv6 addresses, reconfigures + * the interface, and restarts dependent services including DHCP server and dibbler. The function handles + * both IPv4 and IPv6 configurations and manages ULA (Unique Local Address) setup in WAN failover or + * extender modes. + * + * @return None + */ void lan_restart(); + +/** + * @brief Stop the LAN interface and disable network services. + * + * Stops the LAN interface by triggering ipv4-down event, disabling IPv6 on the interface, flushing + * all IPv6 addresses, and stopping the dibbler-server. This function is typically called during + * system shutdown, bridge mode transition, or when the LAN needs to be taken down for configuration + * changes. + * + * @return None + */ void lan_stop(); + +/** + * @brief Teardown and remove a specific L3 network instance. + * + * Tears down a specific L3 network instance by removing its async callbacks, clearing its configuration, + * and removing it from the list of active IPv4 instances. This function unregisters the L2 async event + * handler, calls remove_config to clean up the network configuration, and updates the ipv4-instances + * sysevent variable to reflect the removal. + * + * @param[in] l3_inst - The L3 network instance number to teardown + * + * @return None + */ void teardown_instance(int l3_inst); + +/** + * @brief Resynchronize and bring up a specific L3 network instance. + * + * Brings up a specific L3 network instance by retrieving its configuration from PSM, validating the + * ethernet link association, and triggering the network setup. The function reads L3 instance parameters + * including IP address, subnet mask, and enable status, then initiates the network configuration process. + * In bridge mode, it avoids resyncing the primary LAN instance. This function is typically called when + * adding new network instances or recovering from configuration changes. + * + * @param[in] l3_inst - The L3 network instance number to resynchronize + * + * @return None + */ void resync_instance (int l3_inst); + +/** + * @brief Handle erouter mode update events. + * + * Responds to changes in erouter mode by checking the current bridge mode and IPv4 status configuration. + * When transitioning between routing and bridge modes, it triggers appropriate network reconfiguration. + * The function retrieves the last erouter mode from syscfg and compares it with the current state to + * determine if network services need to be restarted or reconfigured. + * + * @return None + */ void erouter_mode_updated(); + +/** + * @brief Resynchronize IPv4 configuration for a LAN instance. + * + * Resynchronizes the IPv4 configuration for the specified LAN instance by retrieving IP address and + * subnet mask from PSM and applying them to syscfg. This function is typically called when the primary + * LAN instance needs to update its IPv4 configuration after changes in the data model or during recovery + * from configuration inconsistencies. It only processes if the provided instance matches the primary LAN + * L3 network instance. + * + * @param[in] lan_inst - The LAN instance identifier string + * + * @return None + */ void ipv4_resync(char *lan_inst); diff --git a/source/service_dhcp/include/service_dhcp_server.h b/source/service_dhcp/include/service_dhcp_server.h index 1fa9e0d4..0cb02b65 100644 --- a/source/service_dhcp/include/service_dhcp_server.h +++ b/source/service_dhcp/include/service_dhcp_server.h @@ -23,12 +23,104 @@ typedef enum { EXTENDER_MODE, } Dev_Mode; +/** + * @brief Get the current device operating mode. + * + * Retrieves the device mode from syscfg configuration to determine if the device is operating + * as a router or in extender mode. The function reads the "Device_Mode" parameter and converts + * it to the appropriate Dev_Mode enumeration value. + * + * @return The current device operating mode + * @retval ROUTER (0) - Device is operating in router mode + * @retval EXTENDER_MODE (1) - Device is operating in extender mode + */ unsigned int Get_Device_Mode(); #endif +/** + * @brief Stop the DHCP server and related services. + * + * Stops the DHCP server by waiting for it to reach end state, then terminates the dnsmasq process. + * The function checks the current dhcp_server-status and only proceeds if the server is not already stopped. + * In extender mode, it verifies mesh WAN link status before stopping. It kills the dnsmasq process using + * its PID, removes configuration files, and updates the dhcp_server-status sysevent to "stopped". + * + * @return None + */ void dhcp_server_stop(); -int dhcp_server_start (char *); + +/** + * @brief Start the DHCP server with the specified configuration. + * + * Starts the DHCP server by initializing the service, preparing configuration files (hostname, dhcp.conf, + * dnsmasq.conf), and launching the dnsmasq process. The function checks if DHCP server is enabled in syscfg, + * validates the LAN status, handles bridge mode scenarios, and manages the transition from stopped to started state. + * In extender mode, it verifies mesh WAN link is up before proceeding. It handles process restart logic by + * comparing current and previous configurations, and sets up the dhcp_server-status sysevent accordingly. + * + * @param[in] input - Input parameter string + * + * @return The status of the operation + * @retval 0 - DHCP server started successfully or is disabled + * @retval 1 - Failed to start (prerequisites not met) + */ +int dhcp_server_start (char *input); + +/** + * @brief Initialize DHCP service parameters and slow start configuration. + * + * Initializes the DHCP service by retrieving and setting various configuration parameters including + * WAN nameserver propagation, domain propagation, BYOI (Bring Your Own Internet) settings, and slow start + * feature configuration. The function determines if DHCP slow start is needed based on WAN IP address state, + * HSD mode, and temporary IP prefix settings. It sets up slow start quanta and lease time parameters, + * and retrieves device properties for DHCP operation. + * + * @return The status of the operation + * @retval SUCCESS (0) - Initialization completed successfully + */ int service_dhcp_init(); -void lan_status_change(char *); + +/** + * @brief Handle LAN status change events. + * + * Responds to LAN status change events by checking the current lan-status and taking appropriate action. + * If DHCP server is disabled, it starts only the DNS forwarder service by preparing hostname and DNS-only + * configuration. If DHCP server is enabled, it either starts or restarts the DHCP server with full configuration. + * In extender mode, it validates that mesh WAN link is up before proceeding. The function updates dns-status + * and dhcp_server-status sysevent variables accordingly. + * + * @param[in] input - Input parameter string containing LAN status information + * + * @return None + */ +void lan_status_change(char *input); + +/** + * @brief Handle syslog restart request and update DHCP configuration. + * + * Processes syslog restart requests by regenerating DHCP and DNS configuration files based on current + * dhcp_server_enabled setting. The function waits for DNS and DHCP server to reach end state, backs up + * the current dnsmasq.conf, prepares new hostname and DHCP configuration (DNS-only if DHCP server is disabled, + * full configuration otherwise), compares with previous configuration, and restarts the dnsmasq process if + * changes are detected. It only proceeds if dhcp_server-status is "started". + * + * @return The status of the operation + * @retval 0 - Request processed successfully or dhcp_server-status not started + * @retval Non-zero - Error occurred during processing + */ int syslog_restart_request(); -void resync_to_nonvol(char *); + +/** + * @brief Resynchronize DHCP pool configuration to non-volatile storage. + * + * Synchronizes DHCP server pool configurations between current runtime state and PSM (Persistent Storage Manager) + * non-volatile storage. The function compares current DHCP pools with PSM instances, identifies pools to remove + * and pools to load, and updates the configuration accordingly. It handles up to 15 DHCP pools and manages pool + * parameters including Enable, IPInterface, MinAddress, MaxAddress, SubnetMask, and LeaseTime. The function sets + * up async callbacks for pool status monitoring and updates the dhcp_server_current_pools sysevent variable. + * + * @param[in] RemPools - String containing pool instances to remove (NULL to auto-detect from system state) + * + * @return None + */ +void resync_to_nonvol(char *RemPools); diff --git a/source/service_dhcp/include/service_ipv4.h b/source/service_dhcp/include/service_ipv4.h index 40e166e3..7dacecdf 100644 --- a/source/service_dhcp/include/service_ipv4.h +++ b/source/service_dhcp/include/service_ipv4.h @@ -17,16 +17,149 @@ limitations under the License. **************************************************************************/ -void ipv4_up(char *); -void handle_l2_status (int, int, char *, int); +/** + * @brief Bring up an IPv4 L3 network instance. + * + * Brings up the specified IPv4 L3 network instance by checking if a lower L2 instance is associated. + * If no lower L2 instance exists, it calls resync_instance to configure and bring up the network. + * If a lower L2 instance exists, it retrieves the multinet status and calls handle_l2_status to + * process the network state accordingly. + * + * @param[in] l3_inst - String containing the L3 network instance number + * + * @return None + */ +void ipv4_up(char *l3_inst); +/** + * @brief Handle L2 network status changes for an L3 instance. + * + * Processes L2 network status changes and takes appropriate action for the associated L3 instance. + * When the L2 network status is "partial" or "ready" and localready flag is set, it prepares the IPv4 + * configuration by setting the interface name and loading static L3 configuration. When the L2 network + * is down or stopped, it sets the IPv4 status to "pending" and triggers a multinet-up event if needed + * to improve XHome and WAN uptime. + * + * @param[in] l3_inst - The L3 network instance number + * @param[in] l2_inst - The L2 network instance number + * @param[in] net_status - String indicating the network status. + * @param[in] input - Flag indicating if multinet-up event should be triggered when network is down + * + * @return None + */ +void handle_l2_status (int l3_inst, int l2_inst, char *net_status, int input); +/** + * @brief Remove True Static IP (TSIP) configuration from the system. + * + * Removes the True Static IP configuration by retrieving TSIP settings from PSM (IP address, subnet, gateway), + * flushing the interface addresses, deleting routes, and updating system events to reflect the removal. + * The function handles both enabled and disabled TSIP states and cleans up all associated network configuration. + * + * @return None + */ void remove_tsip_config(); +/** + * @brief Remove True Static IP Additional Subnet (TSIP ASN) configurations. + * + * Removes all True Static IP Additional Subnet configurations by iterating through all TSIP ASN instances + * stored in PSM. For each enabled instance (up to MAX_TS_ASN_COUNT), it retrieves the IP address and subnet, + * flushes the interface addresses, deletes associated routes, and cleans up the configuration. The function + * handles multiple subnet instances for advanced static IP routing scenarios. + * + * @return None + */ void remove_tsip_asn_config(); +/** + * @brief Synchronize True Static IP (TSIP) configuration to the system. + * + * Synchronizes the True Static IP configuration from PSM to the active system configuration. The function + * retrieves TSIP settings including enable status, IP address, subnet mask, and gateway from PSM storage, + * calculates network parameters, assigns the IP address to the interface, and adds the necessary routes. + * This is typically called during system initialization or when TSIP configuration changes are detected. + * + * @return None + */ void sync_tsip (); +/** + * @brief Resynchronize True Static IP (TSIP) configuration based on enable state. + * + * Resynchronizes the TSIP configuration by first removing existing TSIP configuration and then applying + * new configuration if TSIP is enabled. The function retrieves TSIP parameters from PSM, removes old settings + * and if tsip_enable parameter is set, it reconfigures the interface with the updated IP address, subnet, and + * gateway settings including route additions. + * + * @param[in] tsip_enable - Flag indicating if TSIP should be enabled (non-zero) or disabled (0) + * + * @return None + */ void resync_tsip(int tsip_enable); +/** + * @brief Synchronize True Static IP Additional Subnet (TSIP ASN) configurations to the system. + * + * Synchronizes all TSIP Additional Subnet configurations from PSM to the active system. The function + * retrieves all TSIP ASN instances from PSM (up to MAX_TS_ASN_COUNT), and for each enabled instance, + * it retrieves the IP address and subnet, calculates network parameters, assigns the additional IP to + * the interface, and adds the necessary routes. This allows multiple static IP subnets to be configured + * on the same interface for advanced networking scenarios. + * + * @return None + */ void sync_tsip_asn (); +/** + * @brief Resynchronize all True Static IP Additional Subnet (TSIP ASN) configurations. + * + * Resynchronizes all TSIP ASN configurations by first removing existing configurations and then reapplying + * them from PSM storage. The function iterates through all TSIP ASN instances, retrieves their enable status, + * IP addresses, and subnet masks, removes old interface addresses and routes, and reconfigures them if enabled. + * This is typically called when TSIP ASN configuration changes are detected or during system recovery. + * + * @return None + */ void resync_tsip_asn(); +/** + * @brief Resynchronize a specific True Static IP Additional Subnet instance. + * + * Resynchronizes a specific TSIP ASN instance identified by the instance number. The function retrieves + * the enable status, IP address, and subnet mask for the specified instance from PSM, validates the parameters, + * calculates network parameters and if enabled, assigns the IP address to the interface + * and adds the necessary route. This provides granular control for updating individual TSIP ASN instances + * without affecting others. + * + * @param[in] instance - The TSIP ASN instance number to resynchronize (must be greater than 0) + * + * @return None + */ void resync_tsip_asn_instance(int instance); +/** + * @brief Apply IPv4 configuration to a specific L3 network instance. + * + * Applies IPv4 configuration to the specified L3 instance by setting the IP address and subnet mask on + * the interface, configuring ARP settings, adding routes to routing tables, and updating system events. + * The function retrieves or uses provided static IPv4 address and subnet, validates them, calculates network + * parameters, assigns the IP to the interface, sets up ARP ignore flags, adds routes for the subnet and + * default gateway, and synchronizes TSIP/TSIP ASN configurations if enabled. In extender mode, it handles + * special IP assignment logic. + * + * @param[in] l3_inst - The L3 network instance number + * @param[in] staticIpv4Addr - Static IPv4 address to apply (NULL to retrieve from sysevent) + * @param[in] staticIpv4Subnet - Static IPv4 subnet mask to apply (NULL to retrieve from sysevent) + * + * @return Configuration status + * @retval TRUE - Configuration applied successfully + * @retval FALSE - Configuration failed (invalid parameters or error during application) + */ BOOL apply_config(int l3_inst, char *staticIpv4Addr, char *staticIpv4Subnet); +/** + * @brief Resynchronize all L3 network instances between active and non-volatile storage. + * + * Resynchronizes all L3 network instances by comparing active instances + * with non-volatile instances . The function identifies instances that need to be + * removed and instances that need to be added . It then calls teardown_instance for + * instances to remove and resync_instance for instances to add, ensuring the active + * network configuration matches the persistent configuration. This is typically called during + * system startup or configuration recovery. + * + * @return None + */ void resync_all_instance(); - + diff --git a/source/service_dhcpv6_client/service_dhcpv6_client.h b/source/service_dhcpv6_client/service_dhcpv6_client.h index f85cb020..419278da 100644 --- a/source/service_dhcpv6_client/service_dhcpv6_client.h +++ b/source/service_dhcpv6_client/service_dhcpv6_client.h @@ -25,12 +25,119 @@ #define SUCCESS 0 extern void* g_vBus_handle; +/** + * @brief Start the DHCPv6 client service. + * + * Starts the DHCPv6 client service by validating prerequisites including erouter mode (IPv6 modes 2 or 3), + * WAN link status, WAN interface configuration, bridge mode, and WAN status. If the PID file exists but the + * process is not running, it triggers a service stop first. If all prerequisites are met, it prepares the + * dibbler client configuration file, creates necessary directories, and starts the dibbler-client process. + * + * @return None + */ void dhcpv6_client_service_start (); + +/** + * @brief Stop the DHCPv6 client service. + * + * Stops the DHCPv6 client service by checking if dibbler client is enabled and terminating the running + * dibbler-client process. The function retrieves the process PID from the PID file, sends appropriate + * signals to terminate the process, waits for process termination, + * and removes the PID file. Platform-specific handling is provided for different hardware configurations. + * + * @return None + */ void dhcpv6_client_service_stop (); + +/** + * @brief Update the DHCPv6 client service state based on enabled flag. + * + * Updates the DHCPv6 client service by checking the dhcpv6c_enabled sysevent flag. If enabled, + * it starts the DHCPv6 client service by calling dhcpv6_client_service_start(). If disabled, + * it stops the service by calling dhcpv6_client_service_stop(). This function is typically called when + * configuration changes require the service state to be synchronized. + * + * @return None + */ void dhcpv6_client_service_update (); + +/** + * @brief Register a sysevent handler for DHCPv6 client service. + * + * Registers a sysevent notification handler for the specified event. The function sets up event options + * if the flag parameter is provided, creates a notification callback, stores the async ID in the appropriate + * global array slot based on event type, and saves the async ID to sysevent for later retrieval. This enables the DHCPv6 client + * service to respond to system events that affect its operation. + * + * @param[in] service_name - The name of the service registering the handler + * @param[in] event_name - The sysevent name to monitor + * @param[in] handler - The handler script or binary to execute when event triggers + * @param[in] flag - Optional flag to set event options (pass non-NULL to enable TUPLE_FLAG_EVENT) + * + * @return None + */ void register_sysevent_handler(char *service_name, char *event_name, char *handler, char *flag); + +/** + * @brief Unregister a sysevent handler for DHCPv6 client service. + * + * Unregisters a previously registered sysevent notification handler for the specified event. The function + * retrieves the stored async ID from sysevent based on the event type, removes the notification callback using sysevent_rmnotification, and + * clears the stored async ID from sysevent. This is called during service shutdown or when event monitoring + * needs to be disabled. + * + * @param[in] service_name - The name of the service unregistering the handler + * @param[in] event_name - The sysevent name to stop monitoring + * + * @return None + */ void unregister_sysevent_handler(char *service_name, char *event_name); + +/** + * @brief Register all sysevent handlers required by DHCPv6 client service. + * + * Registers all sysevent handlers needed by the DHCPv6 client service to monitor system state changes. + * The function registers handlers for erouter_mode-updated, phylink_wan_state, current_wan_ifname, and + * bridge_mode events. It also creates a registration marker file to track that + * handlers have been registered. This is typically called during service enablement. + * + * @return None + */ void register_dhcpv6_client_handler(); + +/** + * @brief Unregister all sysevent handlers for DHCPv6 client service. + * + * Unregisters all sysevent handlers previously registered by the DHCPv6 client service. The function + * unregisters handlers for erouter_mode-updated, phylink_wan_state, current_wan_ifname, and bridge_mode + * events, and removes the registration marker file. This is typically called during + * service disablement to clean up event monitoring resources. + * + * @return None + */ void unregister_dhcpv6_client_handler(); + +/** + * @brief Enable the DHCPv6 client service. + * + * Enables the DHCPv6 client service by checking if it's already enabled via dhcpv6c_enabled sysevent. + * If already enabled, it verifies that event handlers are registered and registers them if missing. + * If not enabled, it starts the DHCPv6 client service, sets the dhcpv6c_enabled flag to "1", and + * registers all necessary sysevent handlers to monitor system state changes. This is the primary entry + * point for enabling DHCPv6 client functionality. + * + * @return None + */ void dhcpv6_client_service_enable (); + +/** + * @brief Disable the DHCPv6 client service. + * + * Disables the DHCPv6 client service by checking if it's currently enabled via dhcpv6c_enabled sysevent. + * If not enabled, it returns immediately. If enabled, it sets the dhcpv6c_enabled flag to "0" and + * unregisters all sysevent handlers to stop monitoring system state changes. This effectively disables + * DHCPv6 client functionality without stopping the currently running dibbler-client process. + * + * @return None + */ void dhcpv6_client_service_disable (); diff --git a/source/service_multinet/Puma6_plat/handle_sw.h b/source/service_multinet/Puma6_plat/handle_sw.h index 21456a46..76508b92 100755 --- a/source/service_multinet/Puma6_plat/handle_sw.h +++ b/source/service_multinet/Puma6_plat/handle_sw.h @@ -81,9 +81,79 @@ const char ATOM_DEP[]="atom-t"; //const char MGMT_PORT_LINUX_IFNAME[]="l2sm0"; +/** + * @brief Add a VLAN to the switch for specified network and ports. + * + * Configures a VLAN on the Puma6 platform switch by enabling VLAN tagging on specified ports, creating + * VLAN interfaces, and managing port memberships. The function retrieves existing port configurations from + * sysevent, enables VLAN on ARM/ATOM/I2E/E2I ports as needed, adds the specified ports to the VLAN using + * swctl commands with appropriate tagging modes (TAGGING_MODE, UNTAGGED_MODE, or NATIVE_MODE), and updates + * sysevent variables to track VLAN port memberships. It handles both internal switch ports (sw_1 through sw_5) + * and external dependency ports (atom, I2E, E2I). + * + * @param[in] net_id - The network instance ID (L2 network identifier) + * @param[in] vlan_id - The VLAN ID to configure (1-4094) + * @param[in] ports_add - Space-separated string of port names to add to the VLAN. + * + * @return None + */ void addVlan(int, int, char*); + +/** + * @brief Set multicast MAC address filtering on switch ports. + * + * Configures multicast MAC address filtering on specific switch ports (I2E port 2, MoCA port 3, and ARM port 7) + * by setting the multicast MAC address 01:00:5E:7F:FF:FA using swctl command with code 23. This enables proper + * multicast traffic handling on the Puma6 platform switch for IGMP snooping and multicast routing scenarios. + * + * @return None + */ void setMulticastMac(); + +/** + * @brief Add IPC (Inter-Process Communication) VLAN to the switch. + * + * Creates and configures the IPC VLAN on the switch by calling addVlan with network ID 0, IPC_VLAN ID, and + * port "sw_6". The IPC VLAN is used for internal communication between different subsystems on the Puma6 + * platform, enabling isolated data plane traffic for system management and control operations. + * + * @return None + */ void addIpcVlan(); + +/** + * @brief Add RADIUS VLAN to the switch for authentication traffic. + * + * Creates and configures the RADIUS VLAN on the switch by calling addVlan with network ID 0, RADIUS_VLAN ID, + * and port "sw_6". The RADIUS VLAN provides a dedicated path for RADIUS authentication, authorization, and + * accounting (AAA) traffic, isolating security-sensitive authentication flows from regular data traffic on + * the Puma6 platform. + * + * @return None + */ void addRadiusVlan(); + +/** + * @brief Create mesh networking VLANs for WiFi mesh backhaul communication. + * + * Creates two mesh VLANs (VLAN 112 and VLAN 113) on the Puma6 platform switch to support WiFi mesh backhaul + * communication. For each VLAN, it configures VLAN tagging on ATOM port 0 and ARM port 7 using swctl with + * TAGGING_MODE, creates the VLAN interface on l2sd0 using vconfig, and assigns link-local IP addresses + * (169.254.0.254/24 for VLAN 112 and 169.254.1.254/24 for VLAN 113) to facilitate mesh node communication + * without external DHCP dependency. + * + * @return None + */ void createMeshVlan(); + +/** + * @brief Add mesh backhaul VLAN to the switch for WiFi mesh traffic. + * + * Creates and configures the mesh backhaul VLAN on the switch by calling addVlan with network ID 0, + * MESHBHAUL_VLAN ID, and port "sw_6". This VLAN is dedicated to carrying WiFi mesh backhaul traffic, + * providing a separate path for mesh node inter-communication and enabling mesh network topology on the + * Puma6 platform. + * + * @return None + */ void addMeshBhaulVlan(); // RDKB-15951 diff --git a/source/service_multinet/Puma6_plat/puma6_plat_map.h b/source/service_multinet/Puma6_plat/puma6_plat_map.h index ebbf1ac8..830044e6 100644 --- a/source/service_multinet/Puma6_plat/puma6_plat_map.h +++ b/source/service_multinet/Puma6_plat/puma6_plat_map.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2015] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -51,6 +51,21 @@ typedef enum puma6Hals { HAL_LINUX } Puma6HalID; +/** +* @brief Generate a sysevent name from a string-based port ID. +* +* @param[in] portID - Pointer to a string containing the port identifier. +* \n The function expects a string-based port ID. +* @param[out] stringbuf - Pointer to a buffer where the generated sysevent name will be stored. +* \n The function formats the output as "if_-status" +* @param[in] bufsize - The size of the stringbuf buffer. +* \n Specifies the maximum number of characters that can be written to stringbuf. +* +* @return The number of bytes required for the sysevent name . +* @retval >0 Number of bytes needed for the complete sysevent name string. +* @retval 0 If operation failed. +* +*/ int eventIDFromStringPortID (void* portID, char* stringbuf, int bufsize); #define NUM_ENTITIES 4 diff --git a/source/service_multinet/Puma6_plat/puma6_plat_sw.h b/source/service_multinet/Puma6_plat/puma6_plat_sw.h index 7a052d37..77a37ae4 100644 --- a/source/service_multinet/Puma6_plat/puma6_plat_sw.h +++ b/source/service_multinet/Puma6_plat/puma6_plat_sw.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2015] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -45,20 +45,112 @@ typedef struct switchPortIDAndState { int portID; char* stringID; - + BOOL vidsLoaded; List taggingVids; // List of vids (ints) unsigned short untaggedVid; unsigned char bVlanEnabled; } SwPortState, *PSwPortState; +/** +* @brief Configure VLAN on external switch ports for Puma6 platform. +* +* @param[in] args - Pointer to an array of SWFabHALArg structures containing port and VLAN configuration. +* \n Each structure includes portID, network instance, VLAN ID, and tagging mode. +* \n The function processes external switch ports and formats them for VLAN operations. +* @param[in] numArgs - The number of arguments in the args array. +* \n Specifies how many ports need to be configured with the VLAN. +* @param[in] up - Boolean flag indicating the operation type. +* \n TRUE to add VLAN configuration, FALSE to delete VLAN configuration. +* +* @return The status of the operation. +* @retval 0 Operation completed successfully. +* +*/ int configVlan_ESW(PSWFabHALArg args, int numArgs, BOOL up); + +/** +* @brief Configure VLAN on internal switch ports for Puma6 platform. +* +* @param[in] args - Pointer to an array of SWFabHALArg structures containing port and VLAN configuration. +* \n Each structure includes portID, network instance, VLAN ID, and tagging mode. +* @param[in] numArgs - The number of arguments in the args array. +* \n Specifies how many internal ports need to be configured with the VLAN. +* @param[in] up - Boolean flag indicating the operation type. +* \n TRUE to add VLAN configuration , FALSE to delete VLAN configuration . +* +* @return The status of the operation. +* @retval 0 Operation completed successfully. +* +*/ int configVlan_ISW(PSWFabHALArg args, int numArgs, BOOL up); + +/** +* @brief Configure VLAN for WiFi interfaces on Puma6 platform. +* +* @param[in] args - Pointer to an array of SWFabHALArg structures containing WiFi interface and VLAN configuration. +* \n Each structure includes portID, network instance, VLAN ID, and tagging mode. +* \n The function concatenates all WiFi interface names and applies VLAN configuration via handle_gre.sh script. +* @param[in] numArgs - The number of arguments in the args array. +* \n Specifies how many WiFi interfaces need to be configured with the VLAN. +* @param[in] up - Boolean flag indicating the operation type. +* \n TRUE to add VLAN configuration , FALSE to delete VLAN configuration . +* +* @return The status of the operation. +* @retval 0 Operation completed successfully. +* +*/ int configVlan_WiFi(PSWFabHALArg args, int numArgs, BOOL up); +/** +* @brief Get the string identifier for an internal switch port. +* +* @param[in] portID - Pointer to a SwPortState structure representing the internal switch port. +* \n The function extracts the stringID field from the SwPortState structure. +* @param[out] stringbuf - Pointer to a buffer where the string identifier will be stored. +* \n The buffer will contain the port's string identifier. +* @param[in] bufSize - The size of the stringbuf buffer. +* \n Specifies the maximum number of characters that can be written to stringbuf. +* +* @return The number of bytes required for the string identifier . +* @retval >0 Number of bytes needed for the complete string identifier. +* @retval 0 If operation failed. +* +*/ int stringIDIntSw (void* portID, char* stringbuf, int bufSize) ; + +/** +* @brief Get the string identifier for an external switch port. +* +* @param[in] portID - Pointer to a SwPortState structure representing the external switch port. +* \n The function extracts the stringID field from the SwPortState structure. +* @param[out] stringbuf - Pointer to a buffer where the string identifier will be stored. +* \n The buffer will contain the port's string identifier. +* @param[in] bufSize - The size of the stringbuf buffer. +* \n Specifies the maximum number of characters that can be written to stringbuf. +* +* @return The number of bytes required for the string identifier . +* @retval >0 Number of bytes needed for the complete string identifier . +* @retval 0 If operation failed. +* +*/ int stringIDExtSw (void* portID, char* stringbuf, int bufSize) ; +/** +* @brief Generate a sysevent name for a switch port. +* +* @param[in] portID - Pointer to a SwPortState structure representing the switch port. +* \n The function extracts the stringID field and generates a sysevent name from it. +* @param[out] stringbuf - Pointer to a buffer where the generated sysevent name will be stored. +* \n The buffer will contain the sysevent name in the format "if_-status". +* @param[in] bufSize - The size of the stringbuf buffer. +* \n Specifies the maximum number of characters that can be written to stringbuf. +* +* @return The number of bytes required for the sysevent name. +* @retval >0 Number of bytes needed for the complete sysevent name string. +* @retval 0 If the operation failed. +* +*/ int eventIDSw (void* portID, char* stringbuf, int bufSize); #endif diff --git a/source/service_multinet/Puma7_plat/puma7_plat_map.h b/source/service_multinet/Puma7_plat/puma7_plat_map.h index 1cf94494..126c70a4 100644 --- a/source/service_multinet/Puma7_plat/puma7_plat_map.h +++ b/source/service_multinet/Puma7_plat/puma7_plat_map.h @@ -35,13 +35,13 @@ /********************************************************************** Copyright [2015] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -65,6 +65,21 @@ typedef enum puma7Hals { HAL_LINUX } Puma6HalID; +/** +* @brief Generate a sysevent name from a string-based port ID. +* +* @param[in] portID - Pointer to a string containing the port identifier. +* \n The function expects a string-based port ID. +* @param[out] stringbuf - Pointer to a buffer where the generated sysevent name will be stored. +* \n The function formats the output as "if_-status" . +* @param[in] bufsize - The size of the stringbuf buffer. +* \n Specifies the maximum number of characters that can be written to stringbuf. +* +* @return The number of bytes required for the sysevent name . +* @retval >0 Number of bytes needed for the complete sysevent name string. +* @retval 0 If operation failed. +* +*/ int eventIDFromStringPortID (void* portID, char* stringbuf, int bufsize); #define NUM_ENTITIES 4 diff --git a/source/service_multinet/Puma7_plat/puma7_plat_sw.h b/source/service_multinet/Puma7_plat/puma7_plat_sw.h index 99c9f2a7..aacd4549 100644 --- a/source/service_multinet/Puma7_plat/puma7_plat_sw.h +++ b/source/service_multinet/Puma7_plat/puma7_plat_sw.h @@ -35,13 +35,13 @@ /********************************************************************** Copyright [2015] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -66,26 +66,176 @@ typedef struct { typedef struct switchPortIDAndState { int portID; char* stringID; - + BOOL vidsLoaded; List taggingVids; // List of vids (ints) unsigned short untaggedVid; unsigned char bVlanEnabled; } SwPortState, *PSwPortState; +/** +* @brief Configure VLAN on external switch ports for Puma7 platform. +* +* @param[in] args - Pointer to an array of SWFabHALArg structures containing port and VLAN configuration. +* \n Each structure includes portID , network instance, bridge name, VLAN ID, and tagging mode. +* \n The function processes external switch ports using portHelper to connect/disconnect ports to/from the bridge. +* @param[in] numArgs - The number of arguments in the args array. +* \n Specifies how many external switch ports need to be configured with the VLAN. +* @param[in] up - Boolean flag indicating the operation type. +* \n TRUE to add port to bridge, FALSE to remove port from bridge. +* +* @return The status of the operation. +* @retval 0 Operation completed successfully. +* @retval Non-zero If operation failed. +* +*/ int configVlan_ESW(PSWFabHALArg args, int numArgs, BOOL up); + +/** +* @brief Configure VLAN for GRE tunnel interfaces on Puma7 platform. +* +* @param[in] args - Pointer to an array of SWFabHALArg structures containing GRE interface and VLAN configuration. +* \n Each structure includes portID (GRE interface name), bridge name, VLAN ID, and tagging mode. +* \n The function connects GRE interfaces to the bridge and configures TCP MSS clamping iptables rules. +* @param[in] numArgs - The number of arguments in the args array. +* \n Specifies how many GRE interfaces need to be configured with the VLAN. +* @param[in] up - Boolean flag indicating the operation type. +* \n TRUE to add GRE interface to bridge with MSS clamping, FALSE to remove interface and rules. +* +* @return The status of the operation. +* @retval 0 Operation completed successfully. +* @retval Non-zero If operation failed. +* +*/ int configVlan_GRE(PSWFabHALArg args, int numArgs, BOOL up); + +/** +* @brief Configure VLAN for generic network interfaces on Puma7 platform. +* +* @param[in] args - Pointer to an array of SWFabHALArg structures containing interface and VLAN configuration. +* \n Each structure includes portID (interface name), bridge name, VLAN ID, and tagging mode. +* \n The function provides generic interface handling using portHelper to connect/disconnect ports to/from the bridge. +* @param[in] numArgs - The number of arguments in the args array. +* \n Specifies how many interfaces need to be configured with the VLAN. +* @param[in] up - Boolean flag indicating the operation type. +* \n TRUE to add interface to bridge, FALSE to remove interface from bridge. +* +* @return The status of the operation. +* @retval 0 Operation completed successfully. +* @retval Non-zero If operation failed. +* +*/ int configVlan_puma7(PSWFabHALArg args, int numArgs, BOOL up); + +/** +* @brief Configure VLAN for WiFi interfaces on Puma7 platform. +* +* @param[in] args - Pointer to an array of SWFabHALArg structures containing WiFi interface and VLAN configuration. +* \n Each structure includes portID, bridge name, VLAN ID, and tagging mode. +* @param[in] numArgs - The number of arguments in the args array. +* \n Specifies how many WiFi interfaces need to be configured with the VLAN. +* @param[in] up - Boolean flag indicating the operation type. +* \n TRUE to add WiFi interface to bridge, FALSE to remove interface from bridge. +* +* @return The status of the operation. +* @retval 0 Operation completed successfully. +* @retval Non-zero If failed. +* +*/ int configVlan_WiFi(PSWFabHALArg args, int numArgs, BOOL up); +/** +* @brief Get the string identifier for an internal switch port. +* +* @param[in] portID - Pointer to a SwPortState structure representing the internal switch port. +* \n The function extracts the stringID field from the SwPortState structure. +* @param[out] stringbuf - Pointer to a buffer where the string identifier will be stored. +* \n The buffer will contain the port's string identifier. +* @param[in] bufSize - The size of the stringbuf buffer. +* \n Specifies the maximum number of characters that can be written to stringbuf. +* +* @return The number of bytes required for the string identifier. +* @retval >0 Number of bytes needed for the complete string identifier. +* @retval 0 If operation failed. +* +*/ int stringIDIntSw (void* portID, char* stringbuf, int bufSize) ; + +/** +* @brief Get the string identifier for an external switch port. +* +* @param[in] portID - Pointer to a SwPortState structure representing the external switch port. +* \n The function extracts the stringID field from the SwPortState structure. +* @param[out] stringbuf - Pointer to a buffer where the string identifier will be stored. +* \n The buffer will contain the port's string identifier. +* @param[in] bufSize - The size of the stringbuf buffer. +* \n Specifies the maximum number of characters that can be written to stringbuf. +* +* @return The number of bytes required for the string identifier. +* @retval >0 Number of bytes needed for the complete string identifier. +* @retval 0 If operation failed. +* +*/ int stringIDExtSw (void* portID, char* stringbuf, int bufSize) ; +/** +* @brief Generate a sysevent name for an external switch port. +* +* @param[in] portID - Pointer to a SwPortState structure representing the external switch port. +* \n The function extracts the stringID field and generates a sysevent name from it. +* @param[out] stringbuf - Pointer to a buffer where the generated sysevent name will be stored. +* \n The buffer will contain the sysevent name in the format "if_-status". +* @param[in] bufSize - The size of the stringbuf buffer. +* \n Specifies the maximum number of characters that can be written to stringbuf. +* +* @return The number of bytes required for the sysevent name. +* @retval >0 Number of bytes needed for the complete sysevent name string. +* @retval 0 If the operation failed. +* +*/ int eventIDSw (void* portID, char* stringbuf, int bufSize); #if defined (MULTILAN_FEATURE) +/** +* @brief Helper function to connect or disconnect ports to or from a bridge. +* +* @param[in] bridge - Pointer to a string containing the bridge name. +* \n Specifies the target bridge for the port operation. +* @param[in] port - Pointer to a string containing the port name. +* \n The port can be a switch port (sw_x) or any network interface name. +* \n If port is sw_x, getIfName is called to get the real interface name. +* @param[in] tagging - Integer flag indicating whether VLAN tagging is enabled. +* \n Non-zero value creates a VLAN interface using vconfig before adding to bridge. +* \n Zero value adds the interface directly without VLAN tagging. +* @param[in] vid - The VLAN ID to be used when tagging is enabled. +* \n This parameter is used with vconfig to create a tagged VLAN interface. +* @param[in] up - Boolean flag indicating the operation type. +* \n TRUE to connect port to bridge (creates VLAN interface if tagging, configures VPID, brings interface up, adds to bridge). +* \n FALSE to disconnect port from bridge (removes from bridge, removes VPID, brings interface down, deletes VLAN interface if tagging). +* +* @return The status of the operation. +* @retval 0 Operation completed successfully. +* @retval Non-zero If operation failed. +* +*/ int portHelper(char *bridge, char *port, int tagging, int vid, BOOL up); + +/** +* @brief Check if a network interface is really connected to a specific bridge. +* +* @param[in] net - Pointer to an L2Net structure representing the bridge network. +* \n The structure contains the bridge name and VLAN ID used for verification. +* @param[in] ifname - Pointer to a string containing the interface name to check. +* \n The interface name can have a "-t" suffix for tagged interfaces, which is stripped during processing. +* \n If ifname is a switch port (sw_x), getIfName is called to resolve the real interface name. +* \n For tagged interfaces, the function appends "." suffix to the real interface name. +* +* @return The bridge connectivity status. +* @retval 1 The interface is NOT connected to the bridge. +* @retval 0 The interface IS connected to the bridge. +* +*/ int ep_check_if_really_bridged(PL2Net net, char *ifname); #endif -#endif +#endif \ No newline at end of file diff --git a/source/services/lib/srvmgr.h b/source/services/lib/srvmgr.h index 75aa0789..09e7e3c0 100644 --- a/source/services/lib/srvmgr.h +++ b/source/services/lib/srvmgr.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -68,51 +68,64 @@ * Purpose : The command line parameter */ typedef enum { - nochoice, - start, - stop, + nochoice, + start, + stop, restart } cmd_type_t; -/* - * Procedure : parse_cmd_line - * Purpose : Figure out what the command line parameter is - * Parameters : - * argc : The number of command line parameters - * argv : The command line string array - * Return Value : the cmd_type_t - */ +/** +* @brief Parse command line parameters to determine service operation. +* +* @param[in] argc - The number of command line parameters. +* \n Specifies the count of command line arguments passed to the program. +* @param[in] argv - The command line string array. +* \n Array of strings containing the command line arguments. +* \n Expected values for argv[1] are "start", "stop", or "restart". +* +* @return The parsed command type. +* @retval start If argv[1] is "start". +* @retval stop If argv[1] is "stop". +* @retval restart If argv[1] is "restart". +* @retval nochoice If argc is less than 2 or argv[1] does not match any expected command. +* +*/ cmd_type_t parse_cmd_line (int argc, char **argv); - -/* - * Procedure : sm_register - * Purpose : Register a service's handler for activation upon default events - * and upon custom events - * Parameters : - * srv_name : The name of the service registering - * default_handler : The path/file to the handler for default events - * custom : Information about the event and handlers using the format: - * event_name | path/file to handler to be activated | - * sysevent activation flags or NULL | sysevent tuple flags or NULL | - * any extra parameters to be given to the handler upon activation - * Note that extra parameters can be a syscfg runtime value (eg $wan_proto), - * a sysevent runtime value (eg @current_wan_ipaddr) or a constant. - * Return Value : - * 0 : success - * <0 : some failure - */ +/** +* @brief Register a service's handler for activation upon default and custom events. +* +* @param[in] srv_name - Pointer to the name of the service registering. +* \n The service name is used to construct default event names (-start, -stop, -restart). +* @param[in] default_handler - Pointer to the path/file to the handler for default events. +* \n This handler will be activated for service start, stop, and restart events. +* \n Default events have tuple flag 0x00000002 set to trigger even when value is unchanged. +* \n Can be NULL if only custom events are needed. +* @param[in] custom - Array of strings containing information about custom events and handlers. +* \n Each string uses the format: "event_name | path/file to handler | sysevent activation flags or NULL | sysevent tuple flags or NULL | extra parameters". +* \n Extra parameters can be syscfg runtime values (e.g., $wan_proto), sysevent runtime values (e.g., @current_wan_ipaddr), or constants. +* \n The array must be NULL-terminated. +* \n Can be NULL if no custom events are needed. +* +* @return The status of the operation. +* @retval 0 Registration successful. +* @retval <0 Registration failed . +* +*/ int sm_register (const char* srv_name, const char* default_handler, const char** custom); -/* - * Procedure : sm_unregister - * Purpose : Unregister all notifications for a service - * Parameters : - * srv_name : The name of the service unregistering - * Return Value : - * 0 : success - * <0 : some failure - */ +/** +* @brief Unregister all event notifications for a service. +* +* @param[in] srv_name - Pointer to the name of the service unregistering. +* \n The function removes all registered handlers for default events (-start, -stop, -restart) and custom events. +* \n Opens connection to syseventd to cancel all async notifications associated with the service. +* +* @return The status of the operation. +* @retval 0 Unregistration successful. +* @retval -1 Unregistration failed. +* +*/ int sm_unregister (const char* srv_name); #endif // _SRVMGR_H_ diff --git a/source/syscfg/lib/syscfg.h b/source/syscfg/lib/syscfg.h index abe62aea..fe8a53a5 100644 --- a/source/syscfg/lib/syscfg.h +++ b/source/syscfg/lib/syscfg.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -62,21 +62,53 @@ extern "C"{ #endif -/* - * Procedure : syscfg_create - * Purpose : Create syscfg shared memory and load entries from persistent storage - * Parameters : - * file - filesystem 'file' where syscfg is stored - * Return Values : - * 0 - success - * ERR_INVALID_PARAM - invalid arguments - * ERR_IO_FAILURE - syscfg file unavailable - * Notes : - */ +/** +* @brief Create syscfg shared memory and load entries from persistent storage. +* +* @param[in] file - Pointer to the filesystem file path where syscfg is stored. +* @param[in] max_file_sz - Maximum file size in bytes for syscfg storage. +* \n If value is greater than 0, uses provided size; otherwise uses DEFAULT_MAX_FILE_SZ. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval ERR_INVALID_PARAM If invalid arguments. +* @retval ERR_SHM_CREATE If shared memory creation failed. +* @retval ERR_IO_FAILURE If syscfg file is unavailable or loading from store failed. +* +*/ int syscfg_create(const char *file, long int max_file_sz); +/** +* @brief Reload syscfg configuration from file. +* +* @param[in] file - Pointer to the configuration file path to reload. +* +* @return The status of the operation. +* @retval 0 Configuration reloaded successfully. +* @retval ERR_INVALID_PARAM If file parameter is NULL. +* @retval Non-zero If error occurred while reloading config file. +* +*/ int syscfg_reload(const char *file); + +/** +* @brief Acquire commit lock for syscfg operations. +* +* @return The status of the lock operation. +* @retval 0 Commit lock acquired successfully. +* @retval Non-zero Lock acquisition failed. +* +*/ int syscfg_commit_lock(); + +/** +* @brief Release commit lock for syscfg operations. +* +* @return The status of the unlock operation. +* @retval 0 Commit lock released successfully. +* @retval Non-zero Lock release failed. +* +*/ int syscfg_commit_unlock(); /* @@ -91,80 +123,201 @@ static inline int syscfg_init (void) return 0; } -/* - * Procedure : syscfg_destroy - * Purpose : Destroy syscfg shared memory context - * Parameters : - * None - * Return Values : - * 0 - success - * ERR_INVALID_PARAM - invalid arguments - * ERR_IO_FAILURE - syscfg file unavailable - * Notes : - * syscfg destroy should happen only during system shutdown. - * *NEVER* call this API in any other scenario!! - */ +/** +* @brief Destroy syscfg shared memory context. +* +* @return None. +* +* @note Syscfg destroy should happen only during system shutdown. NEVER call this API in any other scenario. +* +*/ void syscfg_destroy(); -/* - * Procedure : syscfg_get - * Purpose : Retrieve an entry from syscfg - * Parameters : - * ns - namespace string (optional) - * name - name string, entry to add - * out_val - buffer to store output value string - * outbufsz - output buffer size - * Return Values : - * 0 on success, -1 on error - */ +/** +* @brief Retrieve an entry from syscfg. +* +* @param[in] ns - Pointer to the namespace string (optional). +* @param[in] name - Pointer to the name string of the entry to retrieve. Cannot be NULL. +* @param[out] out_value - Pointer to buffer where the output value string will be stored. +* @param[in] outbufsz - Size of the output buffer in bytes. +* +* @return The status of the operation. +* @retval 0 Entry retrieved successfully. +* @retval -1 If name or out_value is NULL, entry not found, or initialization failed. +* +*/ int syscfg_get(const char *ns, const char *name, char *out_value, int outbufsz); -/* - * Procedure : syscfg_getall - * Purpose : Retrieve all entries from syscfg - * Parameters : - * buf - output buffer to store syscfg entries - * bufsz - size of output buffer - * outsz - number of bytes return into given buffer - * Return Values : - * 0 - on success - * ERR_xxx - various errors codes dependening on the failure - * Notes : - * useful for clients to dump the whole syscfg data - */ +/** +* @brief Retrieve all entries from syscfg. +* +* @param[out] buf - Pointer to output buffer to store syscfg entries. +* @param[in] bufsz - Size of the output buffer in bytes. +* @param[out] outsz - Pointer to store the number of bytes written to the buffer. +* +* @return The status of the operation. +* @retval 0 All entries retrieved successfully. +* @retval ERR_INVALID_PARAM If buf is NULL or bufsz is less. +* @retval ERR_xxx various errors codes dependening on the failure +* +* @note Useful for clients to dump the whole syscfg data. +* +*/ int syscfg_getall(char *buf, int bufsz, int *outsz); -/* - * Like syscfg_getall(), but returns pairs of entries separated by - * newlines instead nul characters. - */ +/** +* @brief Retrieve all entries from syscfg with newline separators. +* +* @param[out] buf - Pointer to output buffer to store syscfg entries. +* @param[in] bufsz - Size of the output buffer in bytes. +* @param[out] outsz - Pointer to store the number of bytes written to the buffer. +* +* @return The status of the operation. +* @retval 0 All entries retrieved successfully. +* @retval ERR_INVALID_PARAM If bufsz is less. +* @retval ERR_xxx various errors codes dependening on the failure +* +* @note Like syscfg_getall(), but returns pairs of entries separated by newlines instead of nul characters. +* +*/ int syscfg_getall2(char *buf, size_t bufsz, size_t *outsz); -/* - * Procedure : syscfg_set - * Purpose : Adds an entry to syscfg - * Parameters : - * ns - namespace string (optional) - * name - name string, entry to add - * value - value string to associate with name - * Return Values : - * 0 - success - * ERR_xxx - various errors codes dependening on the failure - * Notes : - * Only changes syscfg hash table, persistent store contents - * not changed until 'commit' operation - */ - +/** +* @brief Add or update an entry in syscfg with namespace. +* +* @param[in] ns - Pointer to the namespace string. +* @param[in] name - Pointer to the name string of the entry to add. +* @param[in] value - Pointer to the value string to associate with the name. +* +* @return The status of the operation. +* @retval 0 Entry set successfully. +* @retval ERR_INVALID_PARAM If name or value is NULL. +* @retval ERR_xxx various errors codes dependening on the failure. +* +* @note Only changes syscfg hash table; persistent store contents not changed until 'commit' operation. +* +*/ int syscfg_set_ns (const char *ns, const char *name, const char *value); + +/** +* @brief Add or update an entry in syscfg with namespace and commit immediately. +* +* @param[in] ns - Pointer to the namespace string. +* @param[in] name - Pointer to the name string of the entry to add. +* @param[in] value - Pointer to the value string to associate with the name. +* +* @return The status of the operation. +* @retval 0 Entry set and committed successfully. +* @retval ERR_INVALID_PARAM If name or value is NULL. +* @retval ERR_xxx various errors codes dependening on the failure. +* +*/ int syscfg_set_ns_commit (const char *ns, const char *name, const char *value); + +/** +* @brief Add or update an unsigned long entry in syscfg with namespace. +* +* @param[in] ns - Pointer to the namespace string. +* @param[in] name - Pointer to the name string of the entry to add. +* @param[in] value - Unsigned long value to associate with the name. +* +* @return The status of the operation. +* @retval 0 Entry set successfully. +* @retval ERR_INVALID_PARAM If name is NULL. +* @retval ERR_xxx various errors codes dependening on the failure. +* +*/ int syscfg_set_ns_u (const char *ns, const char *name, unsigned long value); + +/** +* @brief Add or update an unsigned long entry in syscfg with namespace and commit immediately. +* +* @param[in] ns - Pointer to the namespace string. +* @param[in] name - Pointer to the name string of the entry to add. +* @param[in] value - Unsigned long value to associate with the name. +* +* @return The status of the operation. +* @retval 0 Entry set and committed successfully. +* @retval ERR_INVALID_PARAM If name is NULL. +* @retval ERR_xxx various errors codes dependening on the failure. +* +*/ int syscfg_set_ns_u_commit (const char *ns, const char *name, unsigned long value); +/** +* @brief Add or update an entry in syscfg without namespace. +* +* @param[in] name - Pointer to the name string of the entry to add. +* @param[in] value - Pointer to the value string to associate with the name. +* +* @return The status of the operation. +* @retval 0 Entry set successfully. +* @retval ERR_INVALID_PARAM If name or value is NULL. +* +*/ int syscfg_set_nns (const char *name, const char *value); + +/** +* @brief Add or update an entry in syscfg without namespace and commit immediately. +* +* @param[in] name - Pointer to the name string of the entry to add. +* @param[in] value - Pointer to the value string to associate with the name. +* +* @return The status of the operation. +* @retval 0 Entry set and committed successfully. +* @retval ERR_INVALID_PARAM If name or value is NULL. +* @retval ERR_xxx various errors codes dependening on the failure. +* +*/ int syscfg_set_nns_commit (const char *name, const char *value); + +/** +* @brief Add or update an unsigned long entry in syscfg without namespace. +* +* @param[in] name - Pointer to the name string of the entry to add. +* @param[in] value - Unsigned long value to associate with the name. +* +* @return The status of the operation. +* @retval 0 Entry set successfully. +* @retval ERR_INVALID_PARAM If name is NULL. +* @retval ERR_xxx various errors codes dependening on the failure. +* +*/ int syscfg_set_nns_u (const char *name, unsigned long value); + +/** +* @brief Add or update an unsigned long entry in syscfg without namespace and commit immediately. +* +* @param[in] name - Pointer to the name string of the entry to add. +* @param[in] value - Unsigned long value to associate with the name. +* +* @return The status of the operation. +* @retval 0 Entry set and committed successfully. +* @retval ERR_INVALID_PARAM If name is NULL. +* @retval ERR_xxx various errors codes dependening on the failure. +* +*/ int syscfg_set_nns_u_commit (const char *name, unsigned long value); +/** +* @brief Add or update an entry in syscfg (wrapper function). +* +* @param[in] ns - Pointer to the namespace string (optional). +* \n If non-NULL, calls syscfg_set_ns to store entry as "ns::name". +* \n If NULL, calls syscfg_set_nns to store entry without namespace. +* @param[in] name - Pointer to the name string of the entry to add. +* \n Cannot be NULL. +* @param[in] value - Pointer to the value string to associate with the name. +* \n Cannot be NULL. +* +* @return The status of the operation. +* @retval 0 Entry set successfully. +* @retval ERR_INVALID_PARAM If name or value is NULL. +* @retval ERR_xxx Various errors codes dependening on the failure. +* +* @note Only changes syscfg hash table; persistent store contents not changed until 'commit' operation. +* +*/ static inline int syscfg_set (const char *ns, const char *name, const char *value) { if (ns) @@ -173,6 +326,21 @@ static inline int syscfg_set (const char *ns, const char *name, const char *valu return syscfg_set_nns (name, value); } +/** +* @brief Add or update an entry in syscfg and commit immediately. +* +* @param[in] ns - Pointer to the namespace string (optional). +* If non-NULL, calls syscfg_set_ns_commit to store entry as "ns::name" and commit. +* If NULL, calls syscfg_set_nns_commit to store entry without namespace and commit. +* @param[in] name - Pointer to the name string of the entry to add. +* @param[in] value - Pointer to the value string to associate with the name. +* +* @return The status of the operation. +* @retval 0 Entry set and committed successfully. +* @retval ERR_INVALID_PARAM If name or value is NULL. +* @retval ERR_xxx Various errors codes dependening on the failure. +* +*/ static inline int syscfg_set_commit (const char *ns, const char *name, const char *value) { if (ns) @@ -181,6 +349,21 @@ static inline int syscfg_set_commit (const char *ns, const char *name, const cha return syscfg_set_nns_commit (name, value); } +/** +* @brief Add or update an unsigned long entry in syscfg. +* +* @param[in] ns - Pointer to the namespace string. +* If non-NULL, calls syscfg_set_ns_u to store entry as "ns::name". +* If NULL, calls syscfg_set_nns_u to store entry without namespace. +* @param[in] name - Pointer to the name string of the entry to add. +* @param[in] value - Unsigned long value to associate with the name. +* +* @return The status of the operation. +* @retval 0 Entry set successfully. +* @retval ERR_INVALID_PARAM If name is NULL. +* @retval ERR_xxx Various errors codes dependening on the failure. +* +*/ static inline int syscfg_set_u (const char *ns, const char *name, unsigned long value) { if (ns) @@ -189,6 +372,21 @@ static inline int syscfg_set_u (const char *ns, const char *name, unsigned long return syscfg_set_nns_u (name, value); } +/** +* @brief Add or update an unsigned long entry in syscfg and commit immediately. +* +* @param[in] ns - Pointer to the namespace string. +* If non-NULL, calls syscfg_set_ns_u_commit to store entry as "ns::name" and commit. +* If NULL, calls syscfg_set_nns_u_commit to store entry without namespace and commit. +* @param[in] name - Pointer to the name string of the entry to add. +* @param[in] value - Unsigned long value to associate with the name. +* +* @return The status of the operation. +* @retval 0 Entry set and committed successfully. +* @retval ERR_INVALID_PARAM If name is NULL. +* @retval ERR_xxx Various errors codes dependening on the failure. +* +*/ static inline int syscfg_set_u_commit (const char *ns, const char *name, unsigned long value) { if (ns) @@ -197,52 +395,50 @@ static inline int syscfg_set_u_commit (const char *ns, const char *name, unsigne return syscfg_set_nns_u_commit (name, value); } -/* - * Procedure : syscfg_unset - * Purpose : Remove an entry from syscfg - * Parameters : - * ns - namespace string (optional) - * name - name string, entry to remove - * Return Values : - * 0 - success - * ERR_xxx - various errors codes dependening on the failure - * Notes : - * Only changes syscfg hash table, persistent store contents - * not changed until 'commit' operation - */ +/** +* @brief Remove an entry from syscfg. +* +* @param[in] ns - Pointer to the namespace string. +* @param[in] name - Pointer to the name string of the entry to remove. +* +* @return The status of the operation. +* @retval 0 Entry removed successfully or entry does not exist. +* @retval ERR_INVALID_PARAM If name is NULL. +* @retval ERR_xxx - various errors codes dependening on the failure. +* +* @note Only changes syscfg hash table; persistent store contents not changed until 'commit' operation. +* +*/ int syscfg_unset(const char *ns, const char *name); -/* - * Procedure : syscfg_commit - * Purpose : commits current stats of syscfg hash table data - * to persistent store - * Parameters : - * None - * Return Values : - * 0 - success - * ERR_IO_xxx - various IO errors dependening on the failure - * Notes : - * WARNING: will overwrite persistent store - * Persistent store location specified during syscfg_create() is cached - * in syscfg shared memory and used as the target for commit - */ +/** +* @brief Commit current state of syscfg hash table data to persistent store. +* +* @return The status of the operation. +* @retval 0 Commit to persistent storage successful. +* @retval ERR_xxx Various IO errors depending on the failure. +* +* @note WARNING: This will overwrite persistent store. Persistent store location specified during +* syscfg_create() is cached in syscfg shared memory and used as the target for commit. +* +*/ int syscfg_commit(); -/* - * Procedure : syscfg_getsz - * Purpose : Get current & maximum peristent storage size - * of syscfg content - * Parameters : - * used_sz - return buffer of used size - * max_sz - return buffer of max size - * Return Values : - * 0 - success - * ERR_xxx - various errors codes dependening on the failure - */ +/** +* @brief Get current and maximum persistent storage size of syscfg content. +* +* @param[out] used_sz - Pointer to store the currently used storage size in bytes. +* @param[out] max_sz - Pointer to store the maximum storage size in bytes. +* +* @return The status of the operation. +* @retval 0 - Retrieved current and maximum persistent storage size successfully. +* @retval ERR_xxx - various errors codes dependening on the failure. +* +*/ int syscfg_getsz (long int *used_sz, long int *max_sz); #ifdef __cplusplus } #endif -#endif /* _SYSCFG_H_ */ +#endif /* _SYSCFG_H_ */ \ No newline at end of file diff --git a/source/syscfg/lib/syscfg_lib.h b/source/syscfg/lib/syscfg_lib.h index 89ae4b60..29b46202 100644 --- a/source/syscfg/lib/syscfg_lib.h +++ b/source/syscfg/lib/syscfg_lib.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -35,7 +35,7 @@ #ifndef _SYSCFG_LIB_H_ #define _SYSCFG_LIB_H_ - + #define SYSCFG_HASH_TABLE_SZ 128 // number of buckets in hash table #define MAX_NAME_LEN 128 // max name len including namespace // size eg "cisco-org:lan0:dhcp:ipaddr" @@ -76,7 +76,7 @@ /* * Number of free table buckets */ -#define NUM_BUCKETS 7 +#define NUM_BUCKETS 7 /* * Current version 0.1 @@ -155,7 +155,7 @@ typedef struct { typedef struct { uint name_sz; uint value_sz; - shmoff_t next; + shmoff_t next; } ht_entry; #define HT_ENTRY(ctx,offset) ((ht_entry *)(((char *)ctx)+offset)) @@ -166,7 +166,7 @@ typedef struct { #define HT_ENTRY_NAME(ctx,offset) ((char *)(((char *)ctx)+offset+sizeof(ht_entry))) #define HT_ENTRY_VALUE(ctx,offset) ((char *)(((char *)ctx)+offset+sizeof(ht_entry)+HT_ENTRY_NAMESZ(ctx,offset))) -/* +/* * WARNING: if you add new elements into this struct, check to see if * offset calculation are still valid. Most often you need to fix them */ @@ -182,29 +182,268 @@ typedef struct { * shm data segments is carved into chunks of 2^ sized elements * shm_mm_alloc(sz) - will allocate a sz byte chunk closest to the chunk size */ +/** +* @brief Create memory management items in shared memory free table. +* +* @param[in] ctx - Pointer to the syscfg shared memory context. +* @param[in,out] ft - Pointer to a single shm_free_table entry. +* +* @return The number of memory management items created. +* @retval >0 Number of mm_items successfully created and added to the free list. +* @retval 0 If operation failed (invalid size or items already available). +* +* @note argument "ft" should be treated as one shm_free_table entry, NOT as ft array. +*/ static int make_mm_items (syscfg_shm_ctx *ctx, shm_free_table *ft); + +/** +* @brief Allocate memory from shared memory pool. +* +* @param[in] ctx - Pointer to the syscfg shared memory context. +* Contains the memory management free table with linked lists of available memory items. +* @param[in] size - The size in bytes to allocate. +* @param[out] out_offset - Pointer to store the allocated memory offset. +* On success, contains the offset to the allocated memory. +* +* @return The status of the operation. +* @retval 0 Memory allocated successfully. +* @retval ERR_MEM_ALLOC If insufficient space available to create new memory items. +* @retval ERR_ENTRY_TOO_BIG If requested size exceeds maximum bucket size. +* +*/ static int shm_malloc (syscfg_shm_ctx *ctx, int size, shmoff_t *out_offset); + +/** +* @brief Free previously allocated memory back to shared memory pool. +* +* @param[in] ctx - Pointer to the syscfg shared memory context. +* Contains the memory management free table where the memory will be returned. +* @param[in] offset - The offset of memory to free (past MM_OVERHEAD). +* The function clears the mm_item's data portion before returning it to the appropriate free list bucket. +* The offset is adjusted to point to the mm_item header (offset - MM_OVERHEAD). +* +* @return None. +* +*/ static void shm_free (syscfg_shm_ctx *ctx, shmoff_t offset); +/** +* @brief Initialize syscfg shared memory context by attaching to existing shared memory. +* +* @return The status of the operation. +* @retval 0 Shared memory context initialized successfully. +* @retval ERR_SHM_NO_FILE If shared memory file (SYSCFG_SHM_FILE) does not exist. +* @retval ERR_SHM_ATTACH If failed to attach to shared memory or magic number check failed. +* +*/ static int syscfg_shm_init (); + +/** +* @brief Create a new syscfg shared memory segment. +* +* @param[in] store_info - Pointer to the store_info_t structure containing storage configuration. +* @param[out] out_shmid - Pointer to store the shared memory ID. +* On success, contains the ID of the newly created shared memory segment. +* +* @return Pointer to the created shared memory context. +* @retval Non-NULL Pointer to syscfg_shm_ctx on successful creation. +* @retval NULL If creation failed (file creation error, old instance present, shmget failed, or control block initialization failed). +* +*/ static void *syscfg_shm_create (store_info_t *store_info, int *out_shmid); + +/** +* @brief Attach to existing syscfg shared memory segment. +* +* @param[out] out_shmid - Pointer to store the shared memory ID. +* On success, contains the ID of the attached shared memory segment. +* +* @return Pointer to the attached shared memory context. +* @retval Non-NULL Pointer to the attached shared memory on success. +* @retval NULL If attachment failed (syscfg_shm_getid failed or shmat failed). +* +*/ static void *syscfg_shm_attach (int *out_shmid); + +/** +* @brief Get the shared memory ID for syscfg. +* +* @return The shared memory ID. +* @retval >0 Valid shared memory ID retrieved using ftok and shmget. +* @retval -1 If ftok or shmget failed (file not found or shared memory segment not available). +* +*/ static int syscfg_shm_getid (); + +/** +* @brief Destroy syscfg shared memory segment and clean up resources. +* +* @param[in] ctx - Pointer to the syscfg shared memory context to destroy. +* The function destroys locks, marks shared memory for deletion using IPC_RMID, detaches from shared memory, and unlinks SYSCFG_SHM_FILE. +* If ctx is NULL, the function returns without performing any operation. +* +* @return None. +* +*/ static void syscfg_shm_destroy (syscfg_shm_ctx *ctx); +/** +* @brief Get current and maximum storage size for syscfg. +* +* @param[out] used_sz - Pointer to store the currently used storage size in bytes. +* @param[out] max_sz - Pointer to store the maximum storage size in bytes. +* +* @return The status of the operation. +* @retval 0 size information retrieved successfully. +* +*/ static int _syscfg_getsz (long int *used_sz, long int *max_sz); + +/** +* @brief Set a syscfg name-value pair in shared memory. +* +* @param[in] ns - Pointer to the namespace string. +* @param[in] name - Pointer to the configuration parameter name string. +* @param[in] value - Pointer to the value string to set. +* @param[in] nolock - Flag indicating if write lock is already acquired by caller. +* +* @return The status of the operation. +* @retval 0 Value set successfully. +* @retval ERR_NO_SPACE If insufficient storage space available to store the tuple. +* @retval Non-zero If hash table entry creation failed. +* +*/ static int _syscfg_set (const char *ns, const char *name, const char *value, int nolock); + +/** +* @brief Unset (remove) a syscfg name-value pair from shared memory. +* +* @param[in] ns - Pointer to the namespace string. +* @param[in] name - Pointer to the configuration parameter name string to unset. +* @param[in] nolock - Flag indicating if write lock is already acquired by caller. +* +* @return The status of the operation. +* @retval 0 Entry unset successfully or entry does not exist. +* +*/ static int _syscfg_unset (const char *ns, const char *name, int nolock); + +/** +* @brief Get the value of a syscfg parameter from shared memory. +* +* @param[in] ns - Pointer to the namespace string. +* @param[in] name - Pointer to the configuration parameter name string. +* +* @return Pointer to the value string. +* @retval Non-NULL Pointer to the value string if the entry exists in shared memory on success. +* @retval NULL If the entry does not exist. +* +*/ static char* _syscfg_get (const char *ns, const char *name); + +/** +* @brief Get all syscfg name-value pairs from shared memory. +* +* @param[out] buf - Pointer to buffer where all name-value pairs will be stored. +* @param[in] bufsz - The size of the buffer in bytes. +* +* @return The number of bytes written to the buffer. +* @retval >0 Number of bytes written (excluding final null terminator). +* +*/ static int _syscfg_getall (char *buf, int bufsz); + +/** +* @brief Get all syscfg name-value pairs from shared memory (alternative format). +* +* @param[out] buf - Pointer to buffer where all name-value pairs will be stored. +* @param[in] bufsz - The size of the buffer in bytes. +* @param[in] nolock - Flag indicating if read lock is already acquired by caller. +* +* @return The number of bytes written to the buffer. +* @retval >0 Number of bytes written (excluding final null terminator). +* +*/ static size_t _syscfg_getall2 (char *buf, size_t bufsz, int nolock); + +/** +* @brief Destroy the syscfg shared memory context. +* +* @return None. +* +*/ static void _syscfg_destroy (); +/** +* @brief Acquire read lock for syscfg shared memory. +* +* @param[in] ctx - Pointer to the syscfg shared memory context. +* +* @return The status of the lock operation. +* @retval 0 Lock acquired successfully. +* @retval Non-zero Lock acquisition failed. +* +*/ static inline int read_lock (syscfg_shm_ctx *ctx); + +/** +* @brief Release read lock for syscfg shared memory. +* +* @param[in] ctx - Pointer to the syscfg shared memory context. +* +* @return The status of the unlock operation. +* @retval 0 Lock released successfully. +* @retval Non-zero Lock release failed. +* +*/ static inline int read_unlock (syscfg_shm_ctx *ctx); + +/** +* @brief Acquire write lock for syscfg shared memory. +* +* @param[in] ctx - Pointer to the syscfg shared memory context. +* +* @return The status of the lock operation. +* @retval 0 Lock acquired successfully. +* @retval Non-zero Lock acquisition failed. +* +*/ static inline int write_lock (syscfg_shm_ctx *ctx); + +/** +* @brief Release write lock for syscfg shared memory. +* +* @param[in] ctx - Pointer to the syscfg shared memory context. +* +* @return The status of the unlock operation. +* @retval 0 Lock released successfully. +* @retval Non-zero Lock release failed. +* +*/ static inline int write_unlock (syscfg_shm_ctx *ctx); + +/** +* @brief Acquire commit lock for syscfg shared memory. +* +* @param[in] ctx - Pointer to the syscfg shared memory context. +* +* @return The status of the lock operation. +* @retval 0 Lock acquired successfully. +* @retval Non-zero Lock acquisition failed. +* +*/ static inline int commit_lock (syscfg_shm_ctx *ctx); + +/** +* @brief Release commit lock for syscfg shared memory. +* +* @param[in] ctx - Pointer to the syscfg shared memory context. +* +* @return The status of the unlock operation. +* @retval 0 Lock released successfully. +* @retval Non-zero Lock release failed. +* +*/ static inline int commit_unlock (syscfg_shm_ctx *ctx); -#endif // _SYSCFG_LIB_H_ +#endif // _SYSCFG_LIB_H_ \ No newline at end of file diff --git a/source/sysevent/lib/libsysevent_internal.h b/source/sysevent/lib/libsysevent_internal.h index 9021127f..083a919f 100644 --- a/source/sysevent/lib/libsysevent_internal.h +++ b/source/sysevent/lib/libsysevent_internal.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -38,149 +38,204 @@ #include "sysevent.h" /* - * Given a *se_msg_hdr calculate the address of the body + * Given a *se_msg_hdr calculate the address of the body * of the message */ /* #define SE_MSG_HDR_2_BODY(a) ((char *)(a) + sizeof(se_msg_hdr)) */ -/* - * Procedure : SE_print_message - * Purpose : Print a message - * Parameters : - * inmsg : The message to print - * type : the type of message - * Return Code : - * 0 : +/** + * @brief Prints the content of a sysevent message for debugging purposes. + * + * @param[in] inmsg Pointer to the message body to print + * @param[in] type The type of message. + * + * @return The status of the operation. + * @retval 0 on success. */ int SE_print_message(char *inmsg, int type); -/* - * Procedure : SE_string2size - * Purpose : Given a string, return the number of bytes - * the string will require in a se_msg_string - * Parameters : - * str : The string - * Return Code : The number of bytes the se_msg_string holding - * this string would required +/** + * @brief Calculates the number of bytes required to hold a string in a se_msg_string structure. + * + * The calculation includes the string length, null terminator and alignment. + * + * @param[in] str The string to measure. + * + * @return The total number of bytes required for se_msg_string including overhead and alignment. + * @retval The total number of bytes required for se_msg_string on success. + * @retval 0 If str is NULL. */ unsigned int SE_string2size(const char *str); -/* - * Procedure : SE_print_message_hdr - * Purpose : Print a message header - * Parameters : - * msg : The message hdr to print - * Return Code : - * 0 : +/** + * @brief Prints a sysevent message header and its body for debugging purposes. + * + * Print a message header and the message like delimiter,mbytes,mtype and sender. + * + * @param[in] hdr Pointer to the se_msg_hdr structure to print + * + * @return The status of the operation. + * @retval 0 on success */ int SE_print_message_hdr(char *hdr); -/* - * Procedure : SE_msg_add_string - * Purpose : Add a string to a SE_msg buffer. The string - * contains an indication of the string size - * and is 32 bit aligned - * the mbytes field of the se_msg_hdr - * Parameters : - * msg : A pointer to the start of the buffer at which to - * add the string - * size : The maximum number of bytes in buffer - * str : the string to add - * Return Code : - * 0 : problem, string not added - * !0 : the number of bytes added to the msg +/** + * @brief Adds a string to a sysevent message buffer as a se_msg_string structure. + * + * The function adds a string with its size field and ensures 32-bit alignment. + * + * @param[in,out] msg Pointer to the buffer where the string will be added + * @param[in] size Maximum number of bytes available in the buffer + * @param[in] str The null-terminated string to add (NULL allowed) + * + * @return Number of bytes added to the message buffer + * @retval >0 Number of bytes added on success + * @retval 0 Error, string not added + * + * @note If str is NULL then the added string will have a length of 0. */ int SE_msg_add_string(char *msg, unsigned int size, const char *str); -/* - * Procedure : SE_msg_hdr_mbytes_fixup - * Purpose : Given a se_msg calculate the - * size and enter that into - * the mbytes field of the se_msg_hdr - * Parameters : - * hdr : A pointer to a complete se_msg_hdr + message - * Return Code : - * 0 : +/** + * @brief Calculates and updates the total message size in the se_msg_hdr structure. + * + * Examines the message type and calculates the total byte count including the header + * and message-specific data structures. The result is stored in the mbytes field of + * the se_msg_hdr. + * + * @param[in,out] hdr Pointer to a complete se_msg_hdr plus message body + * + * @return The status of the operation. + * @retval 0 on success */ int SE_msg_hdr_mbytes_fixup (se_msg_hdr *hdr); -/* - * Procedure : SE_msg_receive - * Purpose : Receive a message from a ready fd - * Parameters : - * fd : The file descriptor to receive from - * replymsg : A buffer to place the reply message - * replymsg_size : The size of the reply message buffer - * On return this contains the number of bytes used - * who : On return the sender as known to the SE Server - * Return Code : - * SE_MSG_NONE : error - * >0 : The type of message returned - * Notes : - * This call will block until a message arrives. +/** + * @brief Receives a sysevent message from a file descriptor with blocking. + * + * This function blocks until a complete message arrives on the file descriptor. + * + * @param[in] fd The file descriptor to receive from. + * @param[out] replymsg Buffer to store the received message. + * @param[in,out] replymsg_size On input: size of replymsg buffer. + * On output: number of bytes received. + * @param[out] who Pointer to receive the sender's token ID as known to the sysevent server. + * + * @return Message type received + * @retval >0 The type of message received on success. + * @retval SE_MSG_NONE Error occurred during receive. + * + * @note This call will block until a message arrives. */ int SE_msg_receive(int fd, char *replymsg, unsigned int *replymsg_size, token_t *who); -/* - * Procedure : SE_minimal_blocking_msg_receive - * Purpose : Receive a message from a ready fd using only a short wait - * Parameters : - * fd : The file descriptor to receive from - * replymsg : A buffer to place the reply message - * replymsg_size : The size of the reply message buffer - * On return this contains the number of bytes used - * who : On return the sender as known to the SE Server - * Return Code : - * SE_MSG_NONE : error - * >0 : The type of message returned - * Notes : - * This call will return SE_MSG_NONE if there is not a message immediately there +/** + * @brief Receives a sysevent message from a file descriptor with minimal blocking. + * + * @param[in] fd The file descriptor to receive from. + * @param[out] replymsg Buffer to store the received message + * @param[in,out] replymsg_size On input: size of replymsg buffer. + * On output: number of bytes received. + * @param[out] who Pointer to receive the sender's token ID as known to the sysevent server + * + * @return Message type received + * @retval >0 The type of message received on success. + * @retval SE_MSG_NONE Error or no message available within timeout period. + * + * @note This call will return SE_MSG_NONE if there is not a message immediately there. */ int SE_minimal_blocking_msg_receive (int fd, char *replymsg, unsigned int *replymsg_size, token_t *who); -/* - * Procedure : SE_msg_send - * Purpose : Send a Data Model message - * Parameters : - * fd : The file descriptor to send to - * sendmsg : The message to send - * Return Code : - * SE_MSG_NONE : error - * >0 : The type of message returned +/** + * @brief Sends a sysevent message to the sysevent daemon. + * + * @param[in] fd The file descriptor to send to + * @param[in] sendmsg Pointer to the complete message including se_msg_hdr and body + * + * @return The status of the operation. + * @retval 0 on success - message sent completely + * @retval -1 Write failed after retries + * @retval -2 Message too large for buffer + * @retval Non-zero for other errors. */ int SE_msg_send (int fd, char *sendmsg); -/* - * Procedure : SE_msg_send_receive - * Purpose : Send a message to the Data Model server and wait for a reply - * Parameters : - * fd : The file descriptor to send to - * sendmsg : The message to send - * replymsg : A buffer to place the reply message - * replymsg_size : The size of the reply message buffer - * On return this contains the number of bytes used - * Return Code : - * SE_MSG_NONE : error - * >0 : The type of message returned +/** + * @brief Sends a sysevent message and waits for a reply with a timeout. + * + * @param[in] fd The file descriptor to send to and receive from + * @param[in] sendmsg Pointer to the complete message to send including se_msg_hdr and body. + * @param[out] replymsg Buffer to store the received reply message. + * @param[in,out] replymsg_size On input: size of replymsg buffer. + * On output: number of bytes received. + * + * @return Message type of the reply. + * @retval >0 The type of reply message received on success. + * @retval SE_MSG_NONE Error occurred or no reply within timeout. + * + * @note This function will NOT block until it receives a reply. */ int SE_msg_send_receive (int fd, char *sendmsg, char *replymsg, unsigned int *replymsg_size); -/* - * Procedure : SE_msg_prepare - * Purpose : Create a sysevent message - * Parameters : - * buf : The message buffer in which to prepare the message - * bufsize : The number of bytes in buf - * mtype : The type of message - * sender : The id of the sender - * Return Code : - * NULL : error - * non NULL : start of the body of the message +/** + * @brief Initializes a sysevent message header in a buffer. + * + * This function create a sysevent message. + * + * @param[out] buf The message buffer in which to prepare the message + * @param[in] bufsize The number of bytes available in buf + * @param[in] mtype The type of message + * @param[in] sender The token ID of the sender + * + * @return Pointer to the start of the message body. + * @retval Non-NULL Pointer to the message body area after the se_msg_hdr on success. + * @retval NULL Error - buf is NULL, bufsize too small, or mtype is 0. */ char *SE_msg_prepare(char *buf, const unsigned int bufsize, const int mtype, const token_t sender); + +/** + * @brief Extracts data from a se_msg_string structure in a message buffer. + * + * Retrieves the data pointer and size from a se_msg_string. + * + * @param[in] msg Pointer to the se_msg_string structure in the message buffer. + * @param[out] size Pointer to store the data length in bytes. + * + * @return Pointer to the data within the se_msg_string. + * @retval Non-NULL Pointer to the data immediately after the size field on success. + * @retval NULL If msg is NULL or data length is 0. + */ char *SE_msg_get_data(char *msg, int *size); + +/** + * @brief Sends a sysevent message containing binary data to the sysevent daemon. + * + * @param[in] fd The file descriptor to send to. + * @param[in,out] sendmsg Pointer to the message buffer containing se_msg_hdr and data. + * @param[in] msgsize Total size of the message in bytes. + * + * @return The status of the operation. + * @retval 0 message sent successfully. + * @retval -1 Write failed after retries. + * @retval -2 Message size exceeds maximum binary message size. + * @retval Non-zero for other errors. + */ int SE_msg_send_data (int fd, char *sendmsg, unsigned int msgsize); + +/** + * @brief Adds binary data to a sysevent message buffer as a se_msg_string structure. + * + * @param[in,out] msg Pointer to the buffer where the data will be added + * @param[in] size Maximum number of bytes available in the buffer + * @param[in] data Pointer to the binary data to add + * @param[in] data_length Length of the data in bytes + * + * @return Number of bytes added to the message buffer + * @retval >0 Number of bytes added (equal to data_length) on success. + * @retval 0 Error - msg is NULL, data is NULL, data_length is 0, or buffer too small + */ int SE_msg_add_data(char *msg, unsigned int size, const char *data, const int data_length); -#endif /* __LIB_SYSEVENT_INTERNAL */ + +#endif /* __LIB_SYSEVENT_INTERNAL */ \ No newline at end of file diff --git a/source/sysevent/lib/sysevent.h b/source/sysevent/lib/sysevent.h index 56feea9f..b726ed27 100644 --- a/source/sysevent/lib/sysevent.h +++ b/source/sysevent/lib/sysevent.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -49,7 +49,7 @@ extern "C" { #define SE_SERVER_WELL_KNOWN_PORT 52367 /* - * Well known UDS + * Well known UDS */ #define UDS_PATH "/tmp/syseventd_connection" @@ -235,16 +235,21 @@ typedef struct { */ #define SE_MSG_STRING_OVERHEAD (sizeof(unsigned int)) -/* - * Procedure : SE_msg_get_string - * Purpose : Get a string from a SE_msg buffer. The buffer - * must be pointing at the se_msg_string containing the string - * Parameters : - * msg : A pointer to the start of the se_msg_string - * size : On return the number of bytes that the se_msg_string occupied - * Return Code : - * NULL : problem, string not gotten - * !NULL : string +/** + * @brief Extracts a string from a se_msg_string structure in a sysevent message buffer. + * + * The buffer pointer must be positioned at the start of a se_msg_string structure. + * Returns the string pointer and the total bytes occupied by the se_msg_string. + * + * @param[in] msg Pointer to the start of the se_msg_string structure. + * @param[out] size On return, contains the number of bytes the se_msg_string occupied. + * + * @return Pointer to the null-terminated string + * @retval non-NULL Pointer to the string within the se_msg_string on success. + * @retval NULL Error - msg is NULL or string has 0 length + * + * @note It is possible for the returned string to be NULL but the size will be positive + * because even a NULL string has a length in the message */ char *SE_msg_get_string(char *msg, int *size); @@ -869,469 +874,521 @@ typedef struct =============================================================== */ -/* - * Procedure : SE_strerror - * Purpose : Return a string version of an error code - * Parameters : - * error : The error - * Return Code : - * The string. - * Do NOT save this string. It has no lifespan +/** + * @brief Returns a human-readable error message for a sysevent error code. + * + * Converts sysevent error codes into descriptive error strings. + * + * @param[in] error The sysevent error code to convert + * + * @return Pointer to a static error message string. + * @retval "Sysevent OK" for error code 0. + * @retval "Unknown Error" for unrecognized codes. + * + * @note Do NOT save this pointer. The string is statically allocated and has + * no guaranteed lifespan. */ char *SE_strerror (int error); -/* - * Procedure : SE_print_mtype - * Purpose : Return a string for a msgtype - * Parameters : - * mtype : The msg type - * Return Code : - * The string. - * Do NOT save this string. It has no lifespan +/** + * @brief Returns a string for a sysevent message type. + * + * Converts sysevent message type codes into descriptive strings. + * + * @param[in] mtype The message type in host byte order + * + * @return Pointer to a static message type string + * + * @note Do NOT save this pointer. The string is statically allocated and has + * no guaranteed lifespan. */ char *SE_print_mtype (int mtype); -/* - * Procedure : init_libsysevent - * Purpose : initialize this library - * Parameters : - * name : name of the user of this library - * Return Code : - * Notes : This doesn't need to be called by most users - * of libsysevent since it is implicitly called during - * sysevent_open. It is used by syseventd. +/** + * @brief Initializes the libsysevent library with a client name. + * + * Saves the client name for use in error messages and debug output. + * + * @param[in] name The name of the library user. + * + * @return None + * + * @note This doesn't need to be called by most users of libsysevent since it is + * implicitly called during sysevent_open. It is used by syseventd. */ void init_libsysevent(const char* const name); -/* - * Procedure : sysevent_open - * Purpose : Connect to the sysevent daemon - * Parameters : - * ip : ip address to connect to. - * This may be dots and dashes or hostname - * port : port to connect to - * version : version of client - * id : name of client - * token : on return, an opaque value to be used in future calls for this session - * Return Code : - * NULL : error - * >0 : file descriptor for connection +/** + * @brief Connects to the sysevent daemon. + * + * Establishes a TCP connection to the sysevent daemon at the specified IP address and port. + * On success, returns a file descriptor. + * + * @param[in] ip IP address to connect to (dots-and-dashes notation or hostname). + * @param[in] port Port number to connect to (must be > 0). + * @param[in] version Protocol version of client (must be 1). + * @param[in] id Client name/identifier. + * @param[out] token On return, opaque token value in future calls for this session + * + * @return File descriptor for the connection. + * @retval >0 Successfully connected file descriptor. + * @retval NULL if error. + * + * @note sysevent_open must be called prior to using any of the other APIs. */ int sysevent_open(char *ip, unsigned short port, int version, char *id, token_t *token); +/** + * @brief Connects to the sysevent daemon for binary data operations. + * + * @param[in] ip IP address to connect to (dots-and-dashes notation or hostname) + * @param[in] port Port number to connect to (must be > 0) + * @param[in] version Protocol version of client (must be 1) + * @param[in] id Client name/identifier + * @param[out] token On return, opaque token value + * + * @return File descriptor for the connection. + * @retval >0 Successfully connected file descriptor. + * @retval -1 if error. + */ int sysevent_open_data (char *ip, unsigned short port, int version, char *id, token_t *token); - -/* - * Procedure : sysevent_local_open - * Purpose : Connect to the sysevent daemon using Unix Domain Socket - * Parameters : - * target : the name of the uds to connect to - * version : version of client - * id : name of client - * token : opaque id for future contact - * Return Code : - * The file descriptor to use in future calls - * -1 if error +/** + * @brief Connects to the sysevent daemon using Unix Domain Socket. + * + * Establishes a connection to the sysevent daemon via Unix Domain Socket instead of TCP/IP. + * + * @param[in] target The name/path of the Unix Domain Socket to connect to. + * @param[in] version Protocol version of client (must be 1). + * @param[in] id Client name/identifier. + * @param[out] token On return, opaque token value. + * + * @return File descriptor for the connection + * @retval >0 Successfully connected file descriptor + * @retval -1 Error occurred */ int sysevent_local_open (char *target, int version, char *id, token_t *token); + +/** + * @brief Connects to the sysevent daemon using Unix Domain Socket for binary data operations. + * + * @param[in] target The name/path of the Unix Domain Socket to connect to. + * @param[in] version Protocol version of client (must be 1) + * @param[in] id Client name/identifier. + * @param[out] token On return, opaque token value. + * + * @return File descriptor for the connection + * @retval >0 Successfully connected file descriptor + * @retval -1 Error occurred + */ int sysevent_local_open_data (char *target, int version, char *id, token_t *token); -/* - * Procedure : sysevent_close - * Purpose : Disconnect from the sysevent daemon - * Parameters : - * fd : the file descriptor to close - * token : The server provided opaque id of the client - * Return Code : - * 0 : disconnected - * !0 : some error +/** + * @brief Disconnects from the sysevent daemon and closes the connection. + * + * Sends an message to the sysevent daemon and closes the file descriptor. + * All registered callbacks and notifications on this connection will be removed. + * + * @param[in] fd The file descriptor to close. + * @param[in] token The server-provided opaque token from connection establishment. + * + * @return The status of the operation. + * @retval 0 Successfully disconnected + * @retval Non-zero Error occurred */ int sysevent_close(const int fd, const token_t token); -/* - * Procedure : sysevent_ping - * Purpose : Ping a connection to the sysevent daemon - * Parameters : - * fd : the file descriptor to ping - * token : Server provided opaque value - * Return Code : - * 0 : ping msg sent - * !0 : some error - * Note : We only told sysevent daemon to ping reply. We are not handling the - * reply itself. That is up to the caller - * Note that there is no current need to ping. If the server - * breaks the connection then there will be a series of SE_MSG_NONE - * coming on the connection. Receipt of several SE_MSG_NONE can be used - * by clients to realize the connection is broken - * - * if you are looking for a blocking ping test which waits for a ping reply - * then use sysevent_ping_test +/** + * @brief Sends a ping message to the sysevent daemon without waiting for reply. + * + * @param[in] fd The file descriptor of the connection + * @param[in] token The server-provided opaque token + * + * @return The status of the operation. + * @retval 0 Ping message sent successfully + * @retval Non-zero Error occurred + * + * @note We only told sysevent daemon to ping reply. We are not handling the reply itself. + * That is up to the caller. Note that there is no current need to ping.If the server breaks + * the connection then there will be a series of SE_MSG_NONE coming on the connection.Receipt + * of several SE_MSG_NONE can be used by clients to realize the connection is broken. If you + * are looking for a blocking ping test which waits for a ping reply then use sysevent_ping_test. */ int sysevent_ping (int fd, token_t token); -/* - * Procedure : sysevent_ping_test - * Purpose : Ping a connection to the sysevent daemon - * AND wait for reply - * Parameters : - * fd : the file descriptor to ping - * token : Server provided opaque value - * tv : A timeval describing how long to wait - * Return Code : - * 0 : ping reply msg received - * !0 : some error +/** + * @brief Sends a ping to the sysevent daemon and waits for a reply. + * + * @param[in] fd The file descriptor of the connection + * @param[in] token The server-provided opaque token + * @param[in] tv Pointer to timeval structure describing how long to wait (NULL for infinite block) + * + * @return The status of the operation. + * @retval 0 Ping reply received successfully + * @retval Non-zero Error or no reply received within timeout + * + * @note This is a BLOCKING call.It is the developer's responsibility + * to specify how long to block. NULL tv = infinite block */ int sysevent_ping_test (int fd, token_t token, struct timeval* tv); -/* - * Procedure : sysevent_get - * Purpose : Send a get to the sysevent daemon and receive reply - * Parameters : - * fd the connection descriptor - * token : The server provided opaque id of the client - * inbuf : A null terminated string which is the thing to get - * outbuf : A buffer to hold returned value - * outbytes : The maximum number of bytes in outbuf - * Return Code : - * 0 : Reply received - * !0 : Some error - * Notes : - * If outbuf is not big enough to hold the reply value, then the value will - * be truncated to fit. An error of ERR_INSUFFICIENT_ROOM will be returned. - * The value will always be NULL terminated, so the outbuf must contain - * enough bytes for the return value as well as the NULL byte. +/** + * @brief Retrieves the value of a tuple from the sysevent daemon. + * + * @param[in] fd The connection file descriptor. + * @param[in] token The server-provided opaque token. + * @param[in] inbuf A Null terminated string which is the thing to get. + * @param[out] outbuf Buffer to hold the returned value. + * @param[in] outbytes Maximum number of bytes in outbuf. + * + * @return The status of the operation. + * @retval 0 Reply received successfully. + * @retval Non-zero Other error occurred. + * + * @note If outbuf is not big enough to hold the reply value, then the value will be truncated to fit. + * An error of ERR_INSUFFICIENT_ROOM will be returned.The value will always be NULL terminated, + * so the outbuf must contain enough bytes for the return value as well as the NULL byte. */ int sysevent_get(const int fd, const token_t token, const char *inbuf, char *outbuf, int outbytes); -/* - * Procedure : sysevent_get_data - * Purpose : Send a get to the sysevent daemon and receive reply - * Parameters : - * fd : The connection id - * token : Server provided opaque value - * inbuf : A null terminated string which is the thing to get - * inbytes : The length of the string not counting terminating null - * outbuf : A buffer to hold returned value - * outbytes : The maximum number of bytes in outbuf - * bufsizecopied : The actual number of bytes copied into outbuf - * Return Code : - * 0 : Reply received - * !0 : Some error - * Notes : - * If outbuf is not big enough to hold the reply value, then the value will - * be truncated to fit. An error of ERR_INSUFFICIENT_ROOM will be returned. - * The value will always be NULL terminated, so the outbuf must contain - * enough bytes for the return value as well as the NULL byte. +/** + * @brief Retrieves binary data value of a tuple from the sysevent daemon. + * + * @param[in] fd The connection file descriptor. + * @param[in] token The server-provided opaque token. + * @param[in] inbuf A Null terminated string which is the thing to get. + * @param[out] outbuf Buffer to hold the returned binary data. + * @param[in] outbytes Maximum number of bytes in outbuf. + * @param[out] actualsizecopied Actual number of bytes copied into outbuf. + * + * @return The status of the operation. + * @retval 0 Reply received successfully + * @retval Non-zero Other error occurred + * + * @note If outbuf is not big enough to hold the reply value, then the value will be truncated to fit. + * An error of ERR_INSUFFICIENT_ROOM will be returned. The value will always be NULL terminated, + * so the outbuf must contain enough bytes for the return value as well as the NULL byte. */ int sysevent_get_data(const int fd, const token_t token, const char *inbuf, char *outbuf, int outbytes,int *actualsizecopied); -/* - * Procedure : sysevent_set - * Purpose : Send a set to the sysevent daemon - * A set may change the value of a tuple - * Parameters : - * fd the connection descriptor - * token : The server provided opaque id of the client - * name : A null terminated string which is the tuple to set - * value : A null terminated string which is the value to set tuple to, or NULL - * Return Code : - * 0 : Success - * !0 : Some error +/** + * @brief Sets the value of a tuple in the sysevent daemon. + * + * @param[in] fd The connection file descriptor + * @param[in] token The server-provided opaque token + * @param[in] name Null-terminated string containing the tuple name to set + * @param[in] value Null-terminated string containing the new value, or NULL to clear + * @param[in] conf_req Configuration request flag + * + * @return The status of the operation. + * @retval 0 Success - value set. + * @retval Non-zero Other error occurred. */ - int sysevent_set(const int fd, const token_t token, const char *name, const char *value, int conf_req); -/* - * Procedure : sysevent_set_data - * Purpose : Send a set to the sysevent daemon - * A set may change the value of a tuple - * Parameters : - * fd : The connection id - * token : Server provided opaque value - * name : A null terminated string which is the tuple to set - * value : buffer holds binary data which is the value to set tuple to, or NULL - * value_length : actual size of binary data buffer - * Return Code : - * 0 : Reply received - * !0 : Some error +/** + * @brief Sets binary data value of a tuple in the sysevent daemon. + * + * @param[in] fd The connection file descriptor. + * @param[in] token The server-provided opaque token. + * @param[in] name Null-terminated string containing the tuple name to set. + * @param[in] value Buffer containing binary data to set, or NULL to clear. + * @param[in] value_length Actual size of binary data buffer in bytes. + * + * @return The status of the operation. + * @retval 0 Success - binary data set. + * @retval Non-zero Other error occurred. */ int sysevent_set_data(const int fd, const token_t token, const char *name, const char *value, int value_length); -/* - * Procedure : sysevent_unset - * Purpose : Send a set to the sysevent daemon - * A set with NULL value of a tuple to clear existing value from volatile memory. - * Parameters : - * fd : The connection id - * token : Server provided opaque value - * name : A null terminated string which is the tuple to set - * value : NULL by default - * Return Code : - * 0 : Reply received - * !0 : Some error +/** + * @brief Clears the value of a tuple from volatile memory. + * + * Send a set to the sysevent daemon. A set with NULL value of a tuple to clear existing value from volatile memory. + * + * @param[in] fd The connection file descriptor. + * @param[in] token The server-provided opaque token. + * @param[in] name Null-terminated string containing the tuple name to unset. + * + * @return The status of the operation. + * @retval 0 Success - tuple value cleared. + * @retval Non-zero Other error occurred. */ int sysevent_unset (const int fd, const token_t token, const char *name); - -/* - * Procedure : sysevent_set_with_tid - * Purpose : Send a set to the sysevent daemon - * A set may change the value of a tuple - * Parameters : - * fd : The connection id - * token : Server provided opaque value - * name : A null terminated string which is the tuple to set - * value : A null terminated string which is the value to set tuple to, or NULL - * source : source of message - * tid : transaction id - * Return Code : - * 0 : Success - * !0 : Some error +/** + * @brief Sets a tuple value with source and transaction ID tracking. + * + * @param[in] fd The connection file descriptor. + * @param[in] token The server-provided opaque token. + * @param[in] name Null-terminated string containing the tuple name to set. + * @param[in] value Null-terminated string containing the new value, or NULL to clear. + * @param[in] source Source identifier of the original message. + * @param[in] tid Transaction ID for tracking message flow. + * + * @return The status of the operation. + * @retval 0 Success - value set with tracking info. + * @retval Non-zero Other error occurred. */ int sysevent_set_with_tid (const int fd, const token_t token, const char *name, const char *value, const int source, const int tid); - -/* - * Procedure : sysevent_set_unique - * Purpose : Send a set unique to the sysevent daemon and receive reply - * A set will create a new tuple with name derived from client request, - * and it will set this new tuple to the value. - * Parameters : - * fd the connection descriptor - * token : The server provided opaque id of the client - * name : A null terminated string which is the namespace of the tuple to create and set - * value : A null terminated string which is the value to set tuple to, or NULL - * outbuf : A buffer to hold returned value - * outbytes : The maximum number of bytes in outbuf - * Return Code : - * 0 : Reply received - * !0 : Some error - * Note that the position of the newly added item within its namespace is not guaranteed to be +/** + * @brief Creates a new unique tuple within a namespace and sets its value. + * + * Send a set unique to the sysevent daemon and receive reply. A set will create + * a new tuple with name derived from client request, and it will set this new tuple to the value. + * + * @param[in] fd The connection file descriptor. + * @param[in] token The server-provided opaque token. + * @param[in] name Null-terminated string containing the namespace prefix. + * @param[in] value Null-terminated string containing the value to set, or NULL. + * @param[out] outbuf Buffer to receive the generated unique tuple name. + * @param[in] outbytes Maximum number of bytes in outbuf. + * + * @return The status of the operation. + * @retval 0 Success - unique tuple created and name returned. + * @retval Non-zero Other error occurred. + * + * @note The position of the newly added item within its namespace is not guaranteed to be * in a particular order when iterating through the space using sysevent_get_unique. * If you need to guarantee that the newly added item is iterated in order of its addition to the * namespace (and are willing to cost the system some memory for each element in the namespace) then - * you must use the ! character as the first character in your namespace + * you must use the ! character as the first character in your namespace. */ int sysevent_set_unique(const int fd, const token_t token, const char *name, const char *value, char *outbuf, int outbytes); -/* - * Procedure : sysevent_get_unique - * Purpose : Send a get for a unique element to the sysevent daemon and receive reply - * This returns the next value. - * Parameters : - * fd the connection descriptor - * token : The server provided opaque id of the client - * inbuf : A null terminated string which is the namespace of the thing to get - * iterator : A iterator which is initialize to NULL - * on return it will contain the next iterator - * subjectbuf : A buffer to hold returned unique name - * subjectbytes : The maximum number of bytes in subjectbuf - * valuebuf : A buffer to hold returned value - * valuebytes : The maximum number of bytes in valuebuf - * Return Code : - * 0 : Reply received - * !0 : Some error - * Notes : - * If either is not big enough to hold the reply value, then the value will - * be truncated to fit. An error of ERR_INSUFFICIENT_ROOM will be returned. - * The value will always be NULL terminated, so the outbuf must contain - * enough bytes for the return value as well as the NULL byte. +/** + * @brief Iterates through unique tuples in a namespace and retrieves the next tuple. + * + * Send a get for a unique element to the sysevent daemon and receive reply. + * This returns the next value. + * + * @param[in] fd The connection file descriptor. + * @param[in] token The server-provided opaque token. + * @param[in] inbuf Null-terminated string containing the namespace to iterate. + * @param[in,out] iterator Iterator tracking position. + * @param[out] subjectbuf Buffer to receive the unique tuple name. + * @param[in] subjectbytes Maximum number of bytes in subjectbuf (including null terminator). + * @param[out] valuebuf Buffer to receive the tuple value. + * @param[in] valuebytes Maximum number of bytes in valuebuf (including null terminator). + * + * @return The status of the operation. + * @retval 0 Next tuple retrieved successfully + * @retval Non-zero Other error occurred + * + * @note If outbuf is not big enough to hold the reply value, then the value will be truncated to fit. + * An error of ERR_INSUFFICIENT_ROOM will be returned. The value will always be NULL terminated, so the + * outbuf must contain enough bytes for the return value as well as the NULL byte. */ int sysevent_get_unique(const int fd, const token_t token, const char *inbuf, unsigned int *iterator, char *subjectbuf, int subjectbytes, char *valuebuf, int valuebytes); -/* - * Procedure : sysevent_del_unique - * Purpose : Send a delete of unique element from its namespace - * Parameters : - * fd the connection descriptor - * token : The server provided opaque id of the client - * inbuf : A null terminated string which is the namespace of the thing to delete - * iterator : A iterator which is describing the element to delete within the namespace - * The first iterator is SYSEVENT_NULL_ITERATOR - * Return Code : - * 0 : +/** + * @brief Deletes a unique tuple element from its namespace. + * + * Sends a message request to remove a specific unique tuple identified by the iterator from the specified namespace. + * + * @param[in] fd The connection file descriptor. + * @param[in] token The server-provided opaque token. + * @param[in] inbuf Null-terminated string containing the namespace. + * @param[in] iterator Pointer to iterator identifying the element to delete within namespace. + * + * @return The status of the operation. + * @retval 0 Element deleted successfully + * @retval Non-zero Other error occurred */ int sysevent_del_unique(const int fd, const token_t token, const char *inbuf, unsigned int *iterator); -/* - * Procedure : sysevent_get_next_iterator - * Purpose : Get the next iterator for a namespace - * Parameters : - * fd the connection descriptor - * token : The server provided opaque id of the client - * inbuf : A null terminated string which is the namespace - * iterator : A iterator which is describing the current iterator. Initially set to 0 - * On return it contains the next iterator to the namespace - * Return Code : - * 0 : +/** + * @brief Gets the next iterator for a namespace without retrieving tuple values. + * + * Sends a message request to advance the iterator to the next element in the namespace without retrieving the tuple name or value. + * + * @param[in] fd The connection file descriptor + * @param[in] token The server-provided opaque token + * @param[in] inbuf Null-terminated string containing the namespace + * @param[in,out] iterator Current iterator position (initialize to 0 for first call). Updated to next position on return. + * On return it contains the next iterator to the namespace. + * + * @return The status of the operation. + * @retval 0 Success - iterator advanced. + * @retval Non-zero Other error occurred. */ int sysevent_get_next_iterator(const int fd, const token_t token, const char *inbuf, unsigned int *iterator); -/* - * Procedure : sysevent_set_options - * Purpose : Send a set options flag to the sysevent daemon and receive reply - * A set may change the event flags of that tuple - * Parameters : - * fd the connection descriptor - * token : The server provided opaque id of the client - * name : A null terminated string which is the tuple to set - * flags : The flags to set tuple to - * Return Code : - * 0 : Success - * !0 : Some error +/** + * @brief Sets the execution control flags for a tuple. + * + * Send a set options flag to the sysevent daemon and receive reply. A set may change + * the event flags of that tuple + * + * @param[in] fd The connection file descriptor. + * @param[in] token The server-provided opaque token. + * @param[in] name A null terminated string which is the tuple to set. + * @param[in] flags The flags to set the option to. + * + * @return The status of the operation. + * @retval 0 Success - flags set. + * @retval Non-zero Other error occurred. */ int sysevent_set_options(const int fd, const token_t token, const char *name, unsigned int flags); -/* - * Procedure : sysevent_setcallback - * Purpose : Declare a program to run when a given tuple changes value - * Parameters : - * fd the connection descriptor - * token : The server provided opaque id of the client - * flags : action_flag_t flags to control the activation - * subject : A null terminated string which is the name of the tuple - * function : An execeutable to call when the tuple changes value - * numparams : The number of arguments in the following char** - * params : A list of 0 or more parameters to use when calling the function - * async_id : On return, and id that can be used to cancel the callback - * Return Code : - * 0 : Success - * !0 : Some error - * Notes : - * When the tuple changes value the executabl3 will be called with all parameters given - * the value of parameters will be either: - * the exact string given as a parameter, or - * if the parameter begins with $ the return will be the current value - * of the trigger by that name. If the trigger does not exist - * then "NULL" will be used. - * For example, if the subject is trigger1, the function /bin/programA, and - * the parameter list is 3 params = trigger1, $trigger3, $trigger1. - * Assuming trigger3 has not yet been set, - * Then when trigger1 changes to "new_value", a process will be forked to - * call /bin/programA "trigger1" "NULL" "new_value" +/** + * @brief Registers an executable to be called when a tuple value changes. + * + * Declare a program to run when a given tuple changes value. + * + * @param[in] fd The connection file descriptor. + * @param[in] token The server-provided opaque token. + * @param[in] flags action_flag_t flags to control the activation. + * @param[in] subject A null terminated string which is the name of the tuple. + * @param[in] function n execeutable to call when the tuple changes value + * @param[in] numparams The number of arguments in the following char**. + * @param[in] params A list of 0 or more parameters to use when calling the function. + * @param[out] async_id On return, ID that can be used to cancel the callback. + * + * @return The status of the operation. + * @retval 0 Success - callback registered. + * @retval Non-zero Other error occurred. + * + * @note When the tuple changes value the executable will be called with all parameters given + * the value of parameters will be either: the exact string given as a parameter, or if the parameter + * begins with $ the return will be the current value of the trigger by that name. If the trigger does + * not exist then "NULL" will be used. For example, if the subject is trigger1, the function /bin/programA, + * and the parameter list is 3 params = trigger1, $trigger3, $trigger1. Assuming trigger3 has not yet been + * set, Then when trigger1 changes to "new_value", a process will be forked to call /bin/programA + * "trigger1" "NULL" "new_value". */ int sysevent_setcallback(const int fd, const token_t token, action_flag_t flags, char *subject, char *function, int numparams, char **params, async_id_t *async_id); -/* - * Procedure : sysevent_rmcallback - * Purpose : Remove an callback/notification from a trigger - * Parameters : - * fd the connection descriptor - * token : The server provided opaque id of the client - * async_id : The async id to remove - * Return Code : - * 0 : Async action is removed +/** + * @brief Removes a registered callback from a tuple. + * + * Remove an callback/notification from a trigger. + * + * @param[in] fd The connection file descriptor. + * @param[in] token A server generated opaque value. + * @param[in] async_id The async id to remove. + * + * @return The status of the operation. + * @retval 0 Callback removed successfully. + * @retval Non-zero Other error occurred. */ int sysevent_rmcallback(const int fd, const token_t token, async_id_t async_id); -/* - * Procedure : sysevent_setnotification - * Purpose : Request a notification message to be sent when a given tuple changes value - * Parameters : - * fd : the connection descriptor - * token : The server provided opaque id of the client - * subject : A null terminated string which is the name of the tuple - * async_id : On return, and id that can be used to cancel the notification - * Return Code : - * 0 : Success - * !0 : Some error - * Note : A notification can only be sent to a client which is still connected - * Note : Notifications are asynchronous and should be sent to a client connection - * which is dedicated to asynchronous sysevent messages. In other words a - * connection which is not shared with a thread doing sets/gets etc. +/** + * @brief Requests notification messages when a tuple value changes. + * + * @param[in] fd The connection file descriptor. + * @param[in] token The server-provided opaque token. + * @param[in] subject Null-terminated string containing the tuple name to monitor. + * @param[out] async_id On return, ID that can be used to cancel the notification + * + * @return The status of the operation. + * @retval 0 Success - notification registered. + * @retval Non-zero Other error occurred. + * + * @note A notification can only be sent to a client which is still connected. + * Notifications are asynchronous and should be sent to a client connection + * which is dedicated to asynchronous sysevent messages. In other words a + * connection which is not shared with a thread doing sets/gets etc. */ int sysevent_setnotification(const int fd, const token_t token, char *subject, async_id_t *async_id); -/* - * Procedure : sysevent_rmnotification - * Purpose : Remove an callback/notification from a trigger - * Parameters : - * fd the connection descriptor - * token : The server provided opaque id of the client - * async_id : The async id to remove - * Return Code : - * 0 : Async action is removed +/** + * @brief Removes a registered notification from a tuple. + * + * Remove an callback/notification from a trigger. + * + * @param[in] fd The connection file descriptor. + * @param[in] token The server-provided opaque token. + * @param[in] async_id The async id to remove. + * + * @return The status of the operation. + * @retval 0 Async action is removed or Notification removed successfully. + * @retval Non-zero Other error occurred. */ int sysevent_rmnotification(const int fd, const token_t token, async_id_t async_id); -/* - * Procedure : sysevent_getnotification - * Purpose : Wait for a notification and return the results when received - * Parameters : - * fd : The connection id - * token : The server provided opaque id of the client - * namebuf : A buffer to hold the name received - * namebytes : The length of the string not counting terminating null - * valbuf : A buffer to hold returned value - * valbytes : On input the maximum number of bytes in outbuf - * On output the actual number of bytes in outbuf not counting - * the terminating null - * async_id : The async id of the action - * Return Code : - * 0 : Reply received - * !0 : Some error - * Notes : - * If a buffer is not big enough to hold the reply value, then the value will - * be truncated to fit. An error of ERR_INSUFFICIENT_ROOM will be returned. - * The value will always be NULL terminated, so the buffer must contain - * enough bytes for the return value as well as the NULL byte. - * Notes - * This will block +/** + * @brief Wait for a notification and return the results when received. + * + * @param[in] fd The connection file descriptor. + * @param[in] token The server-provided opaque token. + * @param[out] namebuf A buffer to hold the name received. + * @param[in,out] namebytes The length of the string not counting terminating null. + * @param[out] valbuf A buffer to hold returned value. + * @param[in,out] valbytes On input the maximum number of bytes in outbuf. + * On output the actual number of bytes in outbuf not counting the terminating null. + * @param[out] async_id The async ID of the notification action. + * + * @return The status of the operation. + * @retval 0 Notification received successfully. + * @retval Non-zero Other error occurred. + * + * @note If a buffer is not big enough to hold the reply value, then the value will + * be truncated to fit. An error of ERR_INSUFFICIENT_ROOM will be returned. + * The value will always be NULL terminated, so the buffer must contain + * enough bytes for the return value as well as the NULL byte.This will block */ int sysevent_getnotification (const int fd, const token_t token, char *namebuf, int *namebytes, char *valbuf, int *valbytes, async_id_t *async_id); -/* - * Procedure : sysevent_getnotification_data - * Purpose : Wait for a notification and return the results when received - * Parameters : - * fd : The connection id - * token : A server generated opaque value - * namebuf : A buffer to hold the name received - * namebytes : The length of the string not counting terminating null - * valbuf : A buffer to hold returned value - * valbytes : On input the maximum number of bytes in outbuf - * On output the actual number of bytes in outbuf - * async_id : The async id of the action - * Return Code : - * 0 : Reply received - * !0 : Some error - * Notes : - * If a buffer is not big enough to hold the reply value, then the value will - * be truncated to fit. An error of ERR_INSUFFICIENT_ROOM will be returned. - * The value will always be NULL terminated, so the buffer must contain - * enough bytes for the return value as well as the NULL byte. - * Notes - * This will block +/** + * @brief Waits for and receives a binary data notification message (blocking call). + * + * @param[in] fd The connection file descriptor. + * @param[in] token The server-provided opaque token + * @param[out] namebuf A buffer to hold the name received. + * @param[in,out] namebytes The length of the string not counting terminating null. + * @param[out] valbuf A buffer to hold returned value. + * @param[in,out] valbytes On input the maximum number of bytes in outbuf. + * On output the actual number of bytes in outbuf. + * @param[out] async_id The async ID of the notification action. + * + * @return The status of the operation. + * @retval 0 Notification received successfully. + * @retval Non-zero Other error occurred. + * + * @note If a buffer is not big enough to hold the reply value, then the value will + * be truncated to fit. An error of ERR_INSUFFICIENT_ROOM will be returned.The value + * will always be NULL terminated, so the buffer must contain enough bytes for the + * return value as well as the NULL byte.This will block. */ int sysevent_getnotification_data (const int fd, const token_t token, char *namebuf, int *namebytes, char *valbuf, int *valbytes, async_id_t *async_id); -/* - * Procedure : sysevent_show - * Purpose : Tell daemon to show all data elements - * Parameters : - * fd : The connection id - * token : The server provided opaque id of the client - * file : A null terminated string which is the file to write to - * Return Code : - * 0 : Success - * !0 : Some error +/** + * @brief Requests the daemon to dump all data elements to a file. + * + * Tell daemon to show all data elements + * + * @param[in] fd The connection file descriptor + * @param[in] token The server-provided opaque token + * @param[in] file Null-terminated string containing the file path to write to + * + * @return The status of the operation. + * @retval 0 Success - show request sent + * @retval Non-zero Other error occurred */ int sysevent_show (const int fd, const token_t token, const char *file); -/* - * Procedure : sysevent_debug - * Purpose : Set sysevent daemon debug level - * Parameters : - * ip : the name or ip address of the sysevent daemon to send msg to - * port : the port of the sysevent daemon to send to - * level : Debug level to set to - * Return Code : - * 0 : debug msg sent - * !0 : some error +/** + * @brief Sets the debug level of the sysevent daemon. + * + * @param[in] ip ip address of the sysevent daemon to send msg to + * @param[in] port the port of the sysevent daemon to send to + * @param[in] level Debug level to set + * + * @return The status of the operation. + * @retval 0 Debug message sent successfully + * @retval Non-zero Other error occurred */ int sysevent_debug (char *ip, unsigned short port, int level); +/** + * @brief Retrieves the maximum binary message size supported by the sysevent daemon. + * + * @return Maximum binary message size in bytes. + * + */ unsigned int sysevent_get_binmsg_maxsize(); #ifdef __cplusplus @@ -1339,4 +1396,4 @@ unsigned int sysevent_get_binmsg_maxsize(); #endif -#endif /* __LIB_SYSEVENT_H_ */ +#endif /* __LIB_SYSEVENT_H_ */ \ No newline at end of file diff --git a/source/sysevent/server/clientsMgr.h b/source/sysevent/server/clientsMgr.h index 84d8e537..3add3b87 100644 --- a/source/sysevent/server/clientsMgr.h +++ b/source/sysevent/server/clientsMgr.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -51,11 +51,11 @@ * Purpose : Hold information about one connected client * Fields : * used : does this structure contain information - * 0 is unused, non-zeof means it contains + * 0 is unused, non-zeof means it contains * information about some connected client * id : id assigned by the server for this client. * This is an opaque value to the client, but - * the client must send this value when + * the client must send this value when * communicating with the server * fd : The file descriptor that the server uses * to communicate with this client @@ -93,128 +93,164 @@ typedef struct { a_client_t *clients; } clients_t; -/* - * Procedure : print_clients_t - * Purpose : print all elements in clientx_t - * Parameters : - * Return Code : - * 0 : OK - */ +/** +* @brief Print all elements in the clients_t structure. +* +* This function prints detailed information about all clients currently managed by the client manager. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int print_clients_t(void); -/* - * Procedure : CLI_MGR_id2fd - * Purpose : Given a client id return the fd of that client - * Parameters : - * id : The client id of the client - * Return Code : - * >0 : The fd that the client listens on - * 0 : client id not found - * <0 : Some error - */ +/** +* @brief Given a client ID, return the file descriptor of that client. +* +* This function looks up a client in the clients table using the provided client ID +* and returns the associated file descriptor used for communication with that client. +* +* @param[in] id - The client ID of the client to look up. +* +* @return The file descriptor of the client or an error code. +* @retval >0 The file descriptor that the client listens on. +* @retval 0 Client ID not found. +* @retval <0 Some error. +* +*/ int CLI_MGR_id2fd (token_t id); -/* - * Procedure : CLI_MGR_fd2id - * Purpose : Given a file descriptor return the corresponding client id - * Parameters : - * fd : A file descriptor - * Return Code : - * NULL : Not a valid client - * token_t : Valid client - * NOTE : - * Due to the multi threaded nature of syseventd, you cannot guarantee anything about - * the client or its validity after this call ends. Don't use the return token - */ +/** +* @brief Given a file descriptor, return the corresponding client ID. +* +* This function looks up a client in the clients table using the provided file descriptor +* and returns the associated client ID (token). +* +* @param[in] fd - A file descriptor. +* +* @return The client ID token +* @retval token_t Valid client ID on success +* @retval TOKEN_INVALID Not a valid client. +* +* @note Due to the multi-threaded nature of syseventd, you cannot guarantee anything about +* the client or its validity after this call ends. Don't use the return token. +*/ token_t CLI_MGR_fd2id (const int fd); -/* - * Procedure : CLI_MGR_new_client - * Purpose : Add a new client to the database of clients - * Parameters : - * name : A printable name assigned by the client - * fp : The connection id for communication with this client - * Return Code : - * non NULL : OK - * NULL : some error. - */ +/** +* @brief Add a new client to the database of clients. +* +* This function creates a new client entry in the clients table, assigns it a unique +* client ID, and associates it with the provided file descriptor for communication. +* +* @param[in] name - A printable name assigned by the client. +* @param[in] fd - The connection ID (file descriptor) for communication with this client. +* +* @return Pointer to the newly created client structure +* @retval Non-NULL pointer to a_client_t structure on success. +* @retval NULL if error occurred. +* +*/ a_client_t *CLI_MGR_new_client(const char *name, const int fd); -/* - * Procedure : CLI_MGR_remove_client_by_fd - * Purpose : Remove a client from the table of clients - * The client is identified by the file descriptor - * that we receive messages from. - * Parameters : - * fd : The file descriptor that we receive messages from that client - * id : The client id, if known - * force : 1 if client data needs to be removed even if id doesnt match CLI_MGR data - * 0 is not force, 1 is force - * Return Code : - * 0 : OK - * < 0 : some error - */ +/** +* @brief Remove a client from the table of clients. +* +* This function removes a client entry from the clients table identified by its file descriptor. +* If the client has registered for notifications, those registrations will be removed as well. +* +* @param[in] fd - The file descriptor that we receive messages from that client. +* @param[in] id - The client ID, if known. +* @param[in] force - Flag to force removal even if ID doesn't match CLI_MGR data. +* \n 0 is not force, 1 is force. +* +* @return The status of the operation. +* @retval 0 on Success. +* @retval <0 on error. +*/ int CLI_MGR_remove_client_by_fd (const int fd, const token_t id, const int force); -/* - * Procedure : CLI_MGR_clear_client_error_by_fd - * Purpose : Clear the number of errors for a client - * The client is identified by the file descriptor - * that we receive messages from. - * Parameters : - * fd : The file descriptor that we receive messages from that client - * Return Code : - * 0 - */ +/** +* @brief Clear the number of errors for a client. +* +* This function resets the error counter to zero for a client identified by its file descriptor. +* +* @param[in] fd - The file descriptor that we receive messages from that client. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int CLI_MGR_clear_client_error_by_fd (int fd); -/* - * Procedure : CLI_MGR_handle_client_error_by_fd - * Purpose : Increment the number of errors for a client - * The client is identified by the file descriptor - * that we receive messages from. - * If the number of errors surpasses a threshold, then force close - * the client - * Parameters : - * fd : The file descriptor that we receive messages from that client - * Return Code : - * 0 : errors incremented - * 1 : client forcibly disconnected - * <0 : an error - */ +/** +* @brief Increment the number of errors for a client and handle threshold. +* +* This function increments the error counter for a client identified by its file descriptor. +* If the number of errors surpasses a threshold, then force closed and removed from the clients table. +* +* @param[in] fd - The file descriptor that we receive messages from that client. +* +* @return The status of the operation. +* @retval 0 Errors incremented. +* @retval 1 Client forcibly disconnected. +* @retval <0 An error occurred. +* +*/ int CLI_MGR_handle_client_error_by_fd (int fd); -/* - * Procedure : CLI_MGR_add_notification_to_client_by_fd - * Purpose : Increment the number of notifications that client has registered for - * The client is identified by the file descriptor - * Parameters : - * fd : The file descriptor that we receive messages from that client - * Return Code : - * 0 : - */ +/** +* @brief Increment the number of notifications that a client has registered for. +* +* This function increments the notification counter for a client identified by its file descriptor. +* This counter tracks how many event notifications the client has subscribed to. +* +* @param[in] fd - The file descriptor that we receive messages from that client. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int CLI_MGR_add_notification_to_client_by_fd (int fd); -/* - * Procedure : CLI_MGR_init_clients_table - * Purpose : Initialize a table of clients - * Parameters : - * Return Code : - * 0 : OK - * <0 : some error. - */ +/** +* @brief Initialize the table of clients. +* +* This function initializes the global clients table. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* @retval <0 Some error occurred. +* +*/ int CLI_MGR_init_clients_table(void); -/* - * Procedure : CLI_MGR_deinit_clients_table - * Purpose : Uninitialize a table of clients - * Parameters : - * Return Code : - * 0 : OK - */ +/** +* @brief Uninitialize the table of clients. +* +* This function cleans up the global clients table by freeing all client structures, +* closing their connections, releasing allocated memory, and resetting the client ID counter. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int CLI_MGR_deinit_clients_table(void); +/** +* @brief Given a client ID, return the client's name. +* +* This function looks up a client in the clients table using the provided client ID +* and returns the client's self-assigned name string. +* +* @param[in] id - The client ID of the client to look up. +* +* @return Pointer to the client's name string. +* @retval Valid client name string on initialization. +* @retval "null" If client ID not found or client manager not initialized. +* +*/ char* CLI_MGR_id2name (token_t id); -#endif // __CLIENTS_MGR_H_ +#endif // __CLIENTS_MGR_H_ \ No newline at end of file diff --git a/source/sysevent/server/dataMgr.h b/source/sysevent/server/dataMgr.h index 8b9a74bf..adbbd608 100644 --- a/source/sysevent/server/dataMgr.h +++ b/source/sysevent/server/dataMgr.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -40,6 +40,15 @@ #include "triggerMgr.h" #ifdef MIMIC_BROADCOM_RC +/** +* @brief Commit data changes. +* +* This function commits pending data changes in the data manager. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int DATA_MGR_commit(); #endif @@ -53,7 +62,7 @@ int DATA_MGR_commit(); * used or empty * source : The original source of this set * tid : The transaction id associated with this element - * trigger_id : The id of the trigger associated with this element, + * trigger_id : The id of the trigger associated with this element, * 0 is no trigger * options : A bitfield describing options. Note that * options are also kept in triggerMgr @@ -90,221 +99,296 @@ typedef struct { } data_element_list_t; -/* - * Procedure : DATA_MGR_get - * Purpose : Get the value of a particular data item - * Parameters : - * name : The data item to retrieve - * value_buf : The buffer to copy the value in - * buf_size : On input the number of bytes in value_buf - * On output the number of bytes copied into value_buf - * subject to the Notes below - * Return Value : - * NULL : No such data item found, or NULL is the data item value - * !NULL : Pointer to the buffer containing the value - * Notes : - * If the value_buf is too small then the value WILL be truncated. - * There will always be a '\0' at the end of the value_buf string - * If the return value of buf_size is >= the input size of buf_size, then - * the value_buf contains a truncated string. The string will be untruncated - * only if outgoing buf_size < incoming buf_size - */ +/** +* @brief Get the value of a particular data item. +* +* This function retrieves the value of a data item identified by its name and copies +* it to the provided buffer. +* +* @param[in] name - The data item to retrieve. +* @param[out] value_buf - The buffer to copy the value in. +* @param[in,out] buf_size - On input the number of bytes in value_buf. +* \n On output the number of bytes copied into value_buf. +* \n subject to the Notes below +* +* @return Pointer to the buffer containing the value. +* @retval Non-NULL Pointer to the buffer containing the value on success. +* @retval NULL No such data item found, or NULL is the data item value. +* +* @note If the value_buf is too small then the value WILL be truncated. There will always +* be a '\0' at the end of the value_buf string. If the return value of buf_size is >= the +* input size of buf_size, then the value_buf contains a truncated string. The string will +* be untruncated only if outgoing buf_size < incoming buf_size. +*/ char *DATA_MGR_get(char *name, char *value_buf, int *buf_size); + +/** +* @brief Get the binary value of a particular data item. +* +* This function retrieves the binary value of a data item identified by its name and +* copies it to the provided buffer. +* +* @param[in] name - The data item to retrieve. +* @param[out] value_buf - The buffer to copy the value in. +* @param[in,out] buf_size - On input the number of bytes in value_buf. +* On output the number of bytes copied into value_buf. +* +* @return Pointer to the buffer containing the value. +* @retval Non-NULL Pointer to the buffer containing the value on success. +* @retval NULL No such data item found, or NULL is the data item value. +* +*/ char *DATA_MGR_get_bin(char *name, char *value_buf, int *buf_size); -/* - * Procedure : DATA_MGR_set - * Purpose : Set the value of a particular data item and if the value has changed - * then execute all actions for that trigger - * Parameters : - * name : The name of the data item to set value - * value : The value to set the data item to - * source : The original source of this set - * tid : Transaction id for this set - * Return Value : - * 0 : Success - * !0 : Some error - */ +/** +* @brief Set the value of a particular data item and execute all actions for that trigger. +* +* This function sets the value of a data item identified by its name. If the value has changed, +* it executes all actions associated with the trigger for that data element. +* +* @param[in] name - The name of the data item to set value. +* @param[in] value - The value to set the data item to. +* @param[in] source - The original source of this set. +* @param[in] tid - Transaction ID for this set. +* @param[in] who - Token identifying the caller. +* +* @return The status of the operation. +* @retval 0 on Success. +* @retval Non-zero on error. +* +*/ int DATA_MGR_set(char *name, char *value, int source, int tid, token_t who); + +/** +* @brief Set the binary value of a particular data item and execute all actions for that trigger. +* +* This function sets the binary value of a data item identified by its name. If the value has changed, +* it executes all actions associated with the trigger for that data element. +* +* @param[in] name - The name of the data item to set value. +* @param[in] value - The binary value to set the data item to. +* @param[in] value_length - The length of the binary value in bytes. +* @param[in] source - The original source of this set. +* @param[in] tid - Transaction ID for this set. +* +* @return The status of the operation. +* @retval 0 on Success. +* @retval Non-Zero on error. +* +*/ int DATA_MGR_set_bin(char *name, char *value, int value_length, int source, int tid); -/* - * Procedure : DATA_MGR_set_unique - * Purpose : Create a unique tuple using name as a seed and set its value - * Parameters : - * name : The preamble name of the data item to create and set value - * value : The value to set the data item to - * uname_buf : The buffer to copy the unique name in - * buf_size : On input the number of bytes in name_buf - * On output the number of bytes copied into name_buf - * subject to the Notes below - * Return Value : Pointer to the buffer containing the assigned unique name - * Notes : - * If the value_buf is too small then the value WILL be truncated. - * There will always be a '\0' at the end of the name_buf string - * If the return value of buf_size is >= the input size of buf_size, then - * the name_buf contains a truncated string. The string will be untruncated - * only if outgoing buf_size < incoming buf_size - */ +/** +* @brief Create a unique tuple using name as a seed and set its value. +* +* This function creates a unique tuple (data element) based on the provided name seed +* and assigns it the specified value. The unique name is returned in the provided buffer. +* +* @param[in] name - The preamble name of the data item to create and set value. +* @param[in] value - The value to set the data item to. +* @param[out] uname_buf - The buffer to copy the unique name in. +* @param[in,out] buf_size - On input the number of bytes in name_buf. +* \n On output the number of bytes copied into name_buf. + * \n subject to the Notes below +* +* @return Pointer to the buffer containing the assigned unique name. +* @retval Pointer to the unique name on success. +* @retval NULL No such data item found, or NULL is the data item value. +* +* @note If the value_buf is too small then the value WILL be truncated. +* There will always be a '\0' at the end of the name_buf string. If the +* return value of buf_size is >= the input size of buf_size, then the name_buf +* contains a truncated string. The string will be untruncated only if outgoing +* buf_size < incoming buf_size. +*/ char *DATA_MGR_set_unique(char *name, char *value, char *uname_buf, int *buf_size); -/* - * Procedure : DATA_MGR_get_unique - * Purpose : Get the value of the next tuple in a namespace - * Parameters : - * name : The namespace - * iterator : An iterator for within the namespace - * sub_buf : The buffer to copy the unique name of the subject - * sub_size : On input the number of bytes in sub_buf. On output the number - * of copied bytes - * value_buf : The buffer to copy the value in - * value_size : On input the number of bytes in value_buf - * On output the number of bytes copied into value_buf - * subject to the Notes below - * Return Value : - * NULL : No such data item found, or NULL is the data item value - * !NULL : Pointer to the buffer containing the value - * Return Value : Pointer to the buffer containing the assigned unique name - * Notes : - * If the value_buf is too small then the value WILL be truncated. - * There will always be a '\0' at the end of the name_buf string - * If the return value of buf_size is >= the input size of buf_size, then - * the name_buf contains a truncated string. The string will be untruncated - * only if outgoing buf_size < incoming buf_size - */ +/** +* @brief Get the value of the next tuple in a namespace. +* +* This function retrieves the next tuple (data element) from a namespace using an iterator. +* Both the unique name and value are returned in the provided buffers. +* +* @param[in] name - The namespace. +* @param[in,out] iterator - An iterator for within the namespace. +* Updated to point to the next element after the current one. +* @param[out] sub_buf - The buffer to copy the unique name of the subject. +* @param[in,out] sub_size - On input the number of bytes in sub_buf. +* On output the number of copied bytes. +* @param[out] value_buf - The buffer to copy the value in. +* @param[in,out] value_size - On input the number of bytes in value_buf. +* \n On output the number of bytes copied into value_buf. +* \n subject to the Notes below +* +* @return Pointer to the buffer containing the value. +* @retval Non-NULL Pointer to the buffer containing the value on success. +* @retval NULL No such data item found, or NULL is the data item value. +* +* @note If the value_buf is too small then the value WILL be truncated. There will +* always be a '\0' at the end of the name_buf string. If the return value of buf_size +* is >= the input size of buf_size, then the name_buf contains a truncated string. The +* string will be untruncated only if outgoing buf_size < incoming buf_size +*/ char *DATA_MGR_get_unique(char *name, unsigned int *iterator, char *sub_buf, unsigned int *sub_size, char *value_buf, unsigned int *value_size); -/* - * Procedure : DATA_MGR_del_unique - * Purpose : Delete one element from a unique namespace - * Parameters : - * name : The namespace - * iterator : An iterator for within the namespace of the element to delete - - * Return Value : - * 0 - */ +/** +* @brief Delete one element from a unique namespace. +* +* This function deletes a specific element from a unique namespace identified by the iterator. +* +* @param[in] name - The namespace. +* @param[in] iterator - An iterator for within the namespace of the element to delete. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int DATA_MGR_del_unique(char *name, unsigned int iterator); -/* - * Procedure : DATA_MGR_get_next_iterator - * Purpose : Given a namespace and an iterator, return the next iterator - * Parameters : - * name : The namespace - * iterator : An iterator for within the namespace - - * Return Value : - * 0 - */ +/** +* @brief Given a namespace and an iterator, return the next iterator. +* +* This function retrieves the next iterator value for traversing a namespace. +* +* @param[in] name - The namespace. +* @param[in,out] iterator - An iterator for within the namespace. +* Updated to point to the next iterator value. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int DATA_MGR_get_next_iterator(char *name, unsigned int *iterator); -/* - * Procedure : DATA_MGR_set_options - * Purpose : Set the option flags of a particular data item - * Parameters : - * name : The name of the data item to set value - * flags : The flag values of the data item - * Return Value : - * 0 : Success - * !0 : Some error - */ +/** +* @brief Set the option flags of a particular data item. +* +* This function sets the tuple option flags for a data item, which control its behavior. +* +* @param[in] name - The name of the data item to set flags. +* @param[in] flags - The flag values of the data item. +* +* @return The status of the operation. +* @retval 0 on Success. +* @retval Non-Zero on error. +* +*/ int DATA_MGR_set_options(char *name, tuple_flag_t flags); -/* - * Procedure : DATA_MGR_get_runtime_values - * Purpose : assign an argument vector to a global argv - * making string substitutions wherever original - * argument starts with $ - * Parameters : - * in_argv : The original argument vector - * Return Code : - * NULL : An error - * !NULL : the argument vector replacement - * Notes : - * The caller must NOT free any of the memory associated with the returned argument - * It will be freed as required by the data manager - * This procedure should be called with the data manager locked - */ +/** +* @brief Assign an argument vector to a global argv making string substitutions. +* +* This function creates a new argument vector by making inline substitutions wherever +* original arguments start with SYSCFG_NAMESPACE_SYMBOL or SYSEVENT_NAMESPACE_SYMBOL. +* +* @param[in] in_argv - The original argument vector. +* +* @return The argument vector replacement. +* @retval Non-NULL The argument vector replacement on success. +* @retval NULL on error occurred. +* +* @note The caller must NOT free any of the memory associated with the returned argument +* It will be freed as required by the data manager. This procedure should be called with +* the data manager locked. +*/ char **DATA_MGR_get_runtime_values (char **in_argv); -/* - * Procedure : DATA_MGR_set_async_external_executable - * Purpose : Set an async notification on a data element which calls an - * external executable when a data variable changes value - * Parameters : - * name : The name of the data item to add a async notification to - * owner : owner of the async notification - * action_flags : Flags to apply to the action - * action : The path and filename of the action to call when the data element changes value - * args : The arguments of the command to add to the action list - * The arguments are expected to be in the form - * arg[0] = path and filename of executable - * arg[1-x] = arguments to send to executable - * last argument is NULL - * trigger_id : On return the id of the trigger - * action_id : On return the id of the action - * Return Value : - * 0 : Success - * !0 : Some error - */ +/** +* @brief Set an async notification on a data element which calls an external executable. +* +* This function registers an asynchronous notification on a data element that executes +* an external program when the data variable changes value. +* +* @param[in] name - The name of the data item to add an async notification to. +* @param[in] owner - Owner of the async notification. +* @param[in] action_flags - Flags to apply to the action. +* @param[in] action - The path and filename of the action to call when the data element changes value. +* @param[in] args - The arguments of the command to add to the action list. +* The arguments are expected to be in the form +* arg[0] = path and filename of executable +* arg[1-x] = arguments to send to executable +* last argument is NULL. +* @param[out] trigger_id - On return the ID of the trigger. +* @param[out] action_id - On return the ID of the action. +* +* @return The status of the operation. +* @retval 0 on Success. +* @retval Non-Zero on error. +* +*/ int DATA_MGR_set_async_external_executable(char *name, token_t owner, action_flag_t action_flags, char *action, char **args, int *trigger_id, int *action_id); -/* - * Procedure : DATA_MGR_set_async_message_notification - * Purpose : Set an async notification on a data element which sends a message - * to the connected client when a data variable changes value - * Parameters : - * name : The name of the data item to add a async notification to - * owner : owner of the async notification - * action_flags : Flags to apply to the action - * trigger_id : On return the id of the trigger - * action_id : On return the id of the action - * Return Value : - * 0 : Success - * !0 : Some error - */ +/** +* @brief Set an async notification on a data element which sends a message. +* +* This function registers an asynchronous notification on a data element that sends +* a message to the connected client when a data variable changes value. +* +* @param[in] name - The name of the data item to add an async notification to. +* @param[in] owner - Owner of the async notification. +* @param[in] action_flags - Flags to apply to the action. +* @param[out] trigger_id - On return the ID of the trigger. +* @param[out] action_id - On return the ID of the action. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval Non-Zero on error. +* +*/ int DATA_MGR_set_async_message_notification(char *name, token_t owner, action_flag_t action_flags, int *trigger_id, int *action_id); -/* - * Procedure : DATA_MGR_remove_async_notification - * Purpose : remove an async notification on a data element - * Parameters : - * trigger_id : On return the id of the trigger - * action_id : On return the id of the action - * owner : owner of the async notification - * Return Value : - * 0 : Success - * !0 : Some error - */ +/** +* @brief Remove an async notification on a data element. +* +* This function removes a previously registered asynchronous notification from a data element. +* +* @param[in] trigger_id - The ID of the trigger. +* @param[in] action_id - The ID of the action. +* @param[in] owner - Owner of the async notification. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval Non-Zero on error. +* +*/ int DATA_MGR_remove_async_notification(int trigger_id, int action_id, const token_t owner); -/* - * Procedure : DATA_MGR_init - * Purpose : Initialize the DATA MGR - * Parameters : - * Return Code : - * 0 : OK - * <0 : some error. - */ +/** +* @brief Initialize the DATA MGR. +* +* This function initializes the data manager by setting up the data element list +* and preparing the internal structures for managing tuples. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* @retval <0 on error. +* +*/ int DATA_MGR_init(void); -/* - * Procedure : DATA_MGR_deinit - * Purpose : Uninitialize the DATA MGR - * Parameters : - * Return Code : - * 0 : OK - */ +/** +* @brief Uninitialize the DATA MGR. +* +* This function cleans up the data manager by freeing all data elements and +* releasing allocated memory. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int DATA_MGR_deinit(void); -/* - * Procedure : DATA_MGR_show - * Purpose : Print the value of all data items known to syseventd - * Parameters : - * file : name of the file to dump the values to - * Return Value : - * 0 - */ +/** +* @brief Print the value of all data items known to syseventd. +* +* This function dumps all data items (tuples). +* +* @param[in] file - Name of the file to dump the values to. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int DATA_MGR_show(char *file); -#endif // __DATA_MGR_H_ +#endif // __DATA_MGR_H_ \ No newline at end of file diff --git a/source/sysevent/server/syseventd.h b/source/sysevent/server/syseventd.h index 8c126dab..70fc65a0 100644 --- a/source/sysevent/server/syseventd.h +++ b/source/sysevent/server/syseventd.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -70,11 +70,11 @@ extern int debug_num_accepts; extern sem_t worker_sem; // number of worker threads created -// note that serialized data tuples are by their nature blocking a thread +// note that serialized data tuples are by their nature blocking a thread // which is serially executing externally defined programs. This is // somewhat dangerous since those programs could be in turn using syseventd. // The number of threads used should be reasonably high. -// Best performance is when the thread count is at the high water level of +// Best performance is when the thread count is at the high water level of // parallel activation calls (determined during boot) // On the other hand, each thread takes memory and too high a count makes syseventd // an attractive candidate for the kernel to choose to kill when Out Of Memory. @@ -90,7 +90,7 @@ extern sem_t worker_sem; #define NUM_CLIENT_ONLY_THREAD 2 // the maximum number of seconds that an activated process can run -// while blocking use of a thread. More than this and the process will +// while blocking use of a thread. More than this and the process will // be killed // This value is changed to 300 sec as some processes are taking time for completing. // e.g Multinet process is taking more time to finish in some of the field units. @@ -113,7 +113,7 @@ typedef struct { int state; // 0=waiting for semaphore, 1=executing, 2=waiting for fork manager } worker_thread_stat_info_t; extern worker_thread_stat_info_t thread_stat_info[NUM_WORKER_THREAD]; - + // thread specific data key extern pthread_key_t worker_data_key; @@ -146,6 +146,20 @@ extern pthread_mutex_t serialization_mutex; extern clients_t global_clients; //deined in clientMgr.c // worker thread init routine +/** +* @brief Worker thread initialization and main loop routine. +* +* This function is the entry point for worker threads. Each worker thread waits on a +* semaphore, processes incoming messages from clients or the main thread, and executes +* the requested operations. The thread continues running until the daemon shuts down. +* +* @param[in] arg - Pointer to worker_thread_private_info_t structure containing +* thread-private data, which is set as thread-specific data. +* +* @return Thread exit value. +* @retval void* NULL on normal exit. +* +*/ extern void *worker_thread_main(void *arg); /* @@ -193,7 +207,7 @@ extern pthread_mutex_t global_serial_msgs_mutex; /* * waiting_pid_t - * When a serial tuple is being handled we keep track of the + * When a serial tuple is being handled we keep track of the * currently handled activated process. If the process takes * too long to complete then it will be killed * pid : pid of the process being waited for @@ -238,7 +252,7 @@ extern pthread_mutex_t stat_info_mutex; /* ====================================================== - triggerMgr stuff + triggerMgr stuff ====================================================== */ // maximum number of arguments we are willing to hold for a client @@ -249,7 +263,7 @@ extern pthread_mutex_t stat_info_mutex; parsing symbols ===================================================== */ -// symbols used to dictate whether a callback parameter is +// symbols used to dictate whether a callback parameter is // looked up in syscfg or sysevent namespace #define SYSCFG_NAMESPACE_SYMBOL '$' #define SYSEVENT_NAMESPACE_SYMBOL '@' @@ -260,75 +274,144 @@ extern pthread_mutex_t stat_info_mutex; ====================================================== */ -/* - * get id assigned to a thread - */ +/** +* @brief Get the ID assigned to a thread. +* +* This function retrieves the thread ID from thread-specific data using the provided key. +* +* @param[in] key - The pthread key for accessing thread-specific data. +* +* @return The thread ID. +* @retval >0 The assigned thread ID on success. +* @retval -1 If thread-specific data is not set or invalid. +* +*/ int thread_get_id(pthread_key_t key); -/* - * get read side of pipe assigned to a thread - */ +/** +* @brief Get the read side of the pipe assigned to a thread. +* +* This function retrieves the file descriptor for the read end of a thread's private pipe +* used for inter-thread communication. +* +* @param[in] key - The pthread key for accessing thread-specific data. +* +* @return The file descriptor for the read end of the pipe. +* @retval >=0 Valid file descriptor on success. +* @retval -1 If thread-specific data is not set or invalid. +* +*/ int thread_get_private_pipe_read(pthread_key_t key); -/* - * statistics - */ +/** +* @brief Set the current state of a thread. +* +* This function sets the state field in the thread's statistics information structure, +* used for monitoring and debugging thread activity. +* +* @param[in] key - The pthread key for accessing thread-specific data. +* @param[in] state - The state value to set. +* 0 = waiting for semaphore +* 1 = executing +* 2 = waiting for fork manager. +* +* @return None. +*/ void thread_set_state(pthread_key_t key, int state); + +/** +* @brief Increment the number of times a thread has been activated. +* +* This function increments the activation counter for a thread, tracking how many times +* the thread has woken up from the semaphore to process work. +* +* @param[in] key - The pthread key for accessing thread-specific data. +* +* @return None. +*/ void thread_activated(pthread_key_t key); -/* - * Procedure : trim - * Purpose : trims a string - * Parameters : - * in : A string to trim - * Return Value : The trimmed string - * Note : This procedure will change the input sting in situ - */ +/** +* @brief Trims whitespace from a string. +* +* This function removes leading and trailing whitespace characters from a string. +* The input string is modified in place. +* +* @param[in,out] in - A string to trim. +* +* @return The trimmed string. +* @retval char* Pointer to the trimmed string on success. +* @retval NULL If input is NULL. +* +* @note This procedure will change the input string in situ. +*/ char *trim(char *in); -/* - * Procedure : sysevent_strdup - * Purpose : strdup - * Parameters : - * s : The sting to duplicate - * file : The file of the procedure that called sysevent_realloc - * line : the line number of the call to sysevent_realloc - * Return Value : A pointer to the allocated store or NULL - */ +/** +* @brief Duplicate a string with debug tracking. +* +* This function duplicates a string similar to strdup() but includes additional +* debug tracking information (file and line number) for memory allocation debugging. +* +* @param[in] s - The string to duplicate. +* @param[in] file - The file of the procedure that called sysevent_strdup. +* @param[in] line - The line number of the call to sysevent_strdup. +* +* @return A pointer to the allocated store. +* @retval Pointer to the duplicated string on success. +* @retval NULL If allocation failed. +* +*/ void *sysevent_strdup(const char* s, char* file, int line); -/* - * Procedure : sysevent_malloc - * Purpose : malloc - * Parameters : - * size : The number of bytes to malloc - * file : The file of the procedure that called sysevent_realloc - * line : the line number of the call to sysevent_realloc - * Return Value : A pointer to the allocated store or NULL - */ +/** +* @brief Allocate memory with debug tracking. +* +* This function allocates memory similar to malloc() but includes additional +* debug tracking information (file and line number) for memory allocation debugging. +* +* @param[in] size - The number of bytes to malloc. +* @param[in] file - The file of the procedure that called sysevent_malloc. +* @param[in] line - The line number of the call to sysevent_malloc. +* +* @return A pointer to the allocated store. +* @retval Pointer to the allocated memory on success. +* @retval NULL If allocation failed. +* +*/ void *sysevent_malloc(size_t size, char* file, int line); -/* - * Procedure : sysevent_realloc - * Purpose : realloc - * Parameters : - * ptr : A pointer to the store to realloc - * size : The number of bytes to realloc - * file : The file of the procedure that called sysevent_realloc - * line : the line number of the call to sysevent_realloc - * Return Value : A pointer to the allocated store or NULL - */ +/** +* @brief Reallocate memory with debug tracking. +* +* This function reallocates memory similar to realloc() but includes additional +* debug tracking information (file and line number) for memory allocation debugging. +* +* @param[in] ptr - A pointer to the store to realloc. +* @param[in] size - The number of bytes to realloc. +* @param[in] file - The file of the procedure that called sysevent_realloc. +* @param[in] line - The line number of the call to sysevent_realloc. +* +* @return A pointer to the allocated store. +* @retval Pointer to the reallocated memory on success. +* @retval NULL If allocation failed. +* +*/ void *sysevent_realloc(void* ptr, size_t size, char* file, int line); -/* - * Procedure : sysevent_free - * Purpose : free - * Parameters : - * addr : The address of the pointer to the store to free - * file : The file of the procedure that called sysevent_realloc - * line : the line number of the call to sysevent_realloc - * Return Value : A pointer to the allocated store or NULL - */ +/** +* @brief Free memory with debug tracking. +* +* This function frees memory similar to free() but includes additional +* debug tracking information (file and line number) for memory allocation debugging. +* The pointer is set to NULL after freeing. +* +* @param[in,out] addr - The address of the pointer to the store to free. +* @param[in] file - The file of the procedure that called sysevent_free. +* @param[in] line - The line number of the call to sysevent_free. +* +* @return None. +*/ void sysevent_free(void **addr, char* file, int line); /* @@ -390,11 +473,73 @@ extern int debugLevel; #define SE_INC_LOG(module, code) #endif +/** +* @brief Print the current timestamp for debug logging. +* +* This function prints the current time in a formatted manner if the SHOW_TIMESTAMP +* debug flag is enabled. +* +* @return returns 1. +* +*/ int printTime(void); + +/** +* @brief Increment a specific statistic counter. +* +* This function increments one of the global statistics counters used for tracking +* various system events and errors in a thread-safe manner. +* +* @param[in] id - The statistic ID to increment. +* Valid values defined in stat_id_t enum. +* +* @return None. +*/ void incr_stat_info(stat_id_t id); + +/** +* @brief Print all statistics counters. +* +* This function prints all global statistics counters to stdout, providing +* visibility into system events and error counts. +* +* @return None. +*/ void printStat(); + +/** +* @brief Get the current time as a formatted string. +* +* This function retrieves the current system time and formats it as a string +* in the format "YYMMDD-HH:MM:SS.microseconds". +* +* @return Pointer to the allocated timestamp string. +* @retval char* Dynamically allocated string containing the formatted timestamp. +* +*/ char* getTime(); + +/** +* @brief Get the system uptime as a formatted string. +* +* This function retrieves the system uptime and formats it as a string containing seconds and nanoseconds. +* +* @return Pointer to the allocated uptime string. +* @retval char* Dynamically allocated string containing the formatted uptime. +* +*/ char* getUpTime(); + +/** +* @brief Write formatted output to the sysevent tracer log file. +* +* This function writes formatted output to /rdklogs/logs/sysevent_tracer.txt if +* the tracer is enabled ( /nvram/sysevent_tracer_enabled). +* +* @param[in] format - Printf-style format string. +* @param[in] ... - Variable arguments corresponding to the format string. +* +*/ void write_to_file(const char *format, ...); -#endif // _SYSEVENTD_H_ +#endif // _SYSEVENTD_H_ \ No newline at end of file diff --git a/source/sysevent/server/triggerMgr.h b/source/sysevent/server/triggerMgr.h index 942ceab0..d1214870 100644 --- a/source/sysevent/server/triggerMgr.h +++ b/source/sysevent/server/triggerMgr.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -52,7 +52,7 @@ and a trigger_t contains pointers to an arbitrary number of trigger_action_t. Each of the above structures are designed to hold arbitrary numbers of other structures. This allows them to grow as required, and in theory to shrink as well (although shrinking is not currently supported since -it does not appear that there will be a need for this). +it does not appear that there will be a need for this). ==================================================================== */ @@ -68,10 +68,10 @@ typedef enum { * An action to execute when a trigger hits * * Fields: - * used : An indication of whether the action is + * used : An indication of whether the action is * used or empty * owner : The owner of the action - * action_flags : The flags of the action + * action_flags : The flags of the action * action_type : The type of action * action_id : The id of the action * action : The path and name of the action @@ -96,7 +96,7 @@ typedef struct { * A trigger is a trigger id along with a set of actions. * * Fields: - * used : An indication of whether the action is + * used : An indication of whether the action is * used or empty * trigger_id : The id of the trigger * max_actions : The maximum number of actions that can be in the list @@ -122,7 +122,7 @@ typedef struct { * * Fields: * mutex : The mutex protecting this data structure - * max_triggers : The maximum number of triggers that can be in the list + * max_triggers : The maximum number of triggers that can be in the list * num_triggers : The number of triggers curerntly in the list * triggers : A list of triggers and notifications */ @@ -153,167 +153,228 @@ be sent as that parameter. */ #ifdef SE_SERVER_CODE_DEBUG -/* - * Procedure : TRIGGER_MGR_print_trigger_list_t - * Purpose : Print the global list of triggers - * Parameters : - * Return Value : - * 0 : Success - */ +/** +* @brief Print the global list of triggers. +* +* This function prints detailed information about all triggers and their associated actions +* in the global trigger list. Used for debugging purposes. +* +* @return The status of the operation. +* @retval 0 Success. +* +*/ int TRIGGER_MGR_print_trigger_list_t(void); #endif -/* - * Procedure : TRIGGER_MGR_set_flags - * Purpose : Set the flags on a trigger - * Parameters : - * target_id : A trigger id if assigned or 0 - * flags : The flags to set to - * trigger_id : On return, The trigger id to set the flag - * Return Value : - * 0 : Success - * !0 : Some error - */ +/** +* @brief Set the flags on a trigger. +* +* This function sets the tuple flags on an existing trigger or creates a new trigger +* with the specified flags. +* +* @param[in] target_id - A trigger ID if assigned or 0 for a new trigger. +* @param[in] flags - The flags to set. +* @param[out] trigger_id - On return, the trigger ID with the flags set. +* +* @return The status of the operation. +* @retval 0 Success. +* @retval Non-zero Some error. +* +* @note This function is called by data manager while it has a mutex lock. DO NOT CALL ANY DATA_MGR functions. +*/ int TRIGGER_MGR_set_flags(int target_id, tuple_flag_t flags, int *trigger_id); -/* - * Procedure : TRIGGER_MGR_remove_actions - * Purpose : Remove all actions owned by an owner for a given trigger - * Parameters : - * trigger_id : The trigger id given when the action was added - * action_id : The action id given when the action was added - * owner : owner of the trigger action - * Return Value : - * 0 : Success - * !0 : Some error - * Note : - * In order to find the appropriate trigger, the trigger_id must match the trigger_id that was returned - * when the action was added, AND the action_id must match the action_id that was given when the - * action was added. - * owner is not currently used, but it is included in the call for future use if needed - */ +/** +* @brief Remove a specific action from a trigger. +* +* This function removes an action from a trigger identified by the trigger ID and action ID. +* The trigger and action IDs must match those returned when the action was originally added. +* +* @param[in] trigger_id - The trigger ID given when the action was added. +* @param[in] action_id - The action ID given when the action was added. +* @param[in] owner - Owner of the trigger action. +* +* @return The status of the operation. +* @retval 0 Success. +* @retval Non-zero Some error. +* +* @note In order to find the appropriate trigger, the trigger_id must match the trigger_id that was returned +* when the action was added, AND the action_id must match the action_id that was given when the action was added. +* owner is not currently used, but it is included in the call for future use if needed. +*/ int TRIGGER_MGR_remove_action(int trigger_id, int action_id, const token_t owner); -/* - * Procedure : TRIGGER_MGR_remove_trigger - * Purpose : Remove all actions owned by a trigger and remove the trigger - * Parameters : - * trigger_id : The trigger id of the trigger to remove - * Return Value : - * 0 : Success - * !0 : Some error - */ +/** +* @brief Remove all actions owned by a trigger and remove the trigger. +* +* This function removes all actions associated with a trigger and then removes the trigger itself, +* freeing all associated resources. +* +* @param[in] trigger_id - The trigger ID of the trigger to remove. +* +* @return The status of the operation. +* @retval 0 Success. +* @retval Non-zero some error. +* +*/ int TRIGGER_MGR_remove_trigger(int trigger_id); -/* - * Procedure : TRIGGER_MGR_add_executable_call_action - * Purpose : Add an action to call an external executable to be executed when a trigger value changes - * Parameters : - * target_id : The trigger_id to which to add this action. - * 0 means a new trigger should be assigned - * owner : owner of the trigger action - * action_flags : Flags to apply to this action - * action : The path and filename of the action to call when the trigger changes value - * args : The arguments of the command to add to the action list - * The arguments are expected to be in the form - * arg[0] = path and filename of executable - * arg[1-x] = arguments to send to executable - * last argument is NULL - * trigger_id : On return the id of the trigger - * action_id : On return the id of the action - * Return Value : - * 0 : Success - * !0 : Some error - */ +/** +* @brief Add an action to call an external executable when a trigger value changes. +* +* This function registers an action that executes an external program when the trigger's associated data +* tuple changes value. The action is added to the specified trigger, or a new trigger is created if target_id is 0. +* +* @param[in] target_id - The trigger_id to which to add this action. +* 0 means a new trigger should be assigned. +* @param[in] owner - Owner of the trigger action. +* @param[in] action_flags - Flags to apply to this action. +* @param[in] action - The path and filename of the action to call when the trigger changes value. +* @param[in] args - The arguments of the command to add to the action list. +* The arguments are expected to be in the form: +* arg[0] = path and filename of executable +* arg[1-x] = arguments to send to executable +* last argument is NULL. +* @param[out] trigger_id - On return the ID of the trigger. +* @param[out] action_id - On return the ID of the action. +* +* @return The status of the operation. +* @retval 0 Success. +* @retval Non-zero some error. +* +* @note This function is called by data manager while it has a mutex lock. DO NOT CALL ANY DATA_MGR functions. +*/ int TRIGGER_MGR_add_executable_call_action(int target_id, const token_t owner, action_flag_t action_flags, char *action, char **args, int *trigger_id, int *action_id); -/* - * Procedure : TRIGGER_MGR_add_notification_message_action - * Purpose : Add an action to send a message to be sent when a trigger value changes - * Parameters : - * target_id : The trigger_id to which to add this action. - * 0 means a new trigger should be assigned - * owner : owner of the trigger action - * action_flags : Flags to apply to this action - * trigger_id : On return the id of the trigger - * action_id : On return the id of the action - * Return Value : - * 0 : Success - * !0 : Some error - */ +/** +* @brief Add an action to send a message when a trigger value changes. +* +* This function add an action to call an external executable which will be executed when a trigger value changes. +* +* @param[in] target_id - The trigger_id to which to add this action. +* 0 means a new trigger should be assigned. +* @param[in] owner - Owner of the trigger action. +* @param[in] action_flags - Flags to apply to this action. +* @param[out] trigger_id - On return the ID of the trigger. +* @param[out] action_id - On return the ID of the action. +* +* @return The status of the operation. +* @retval 0 Success. +* @retval Non-zero Some error. +* +* @note This function is called by data manager while it has a mutex lock. DO NOT CALL ANY DATA_MGR functions. +*/ int TRIGGER_MGR_add_notification_message_action(int target_id, const token_t owner, action_flag_t action_flags, int *trigger_id, int *action_id); -/* - * Procedure : TRIGGER_MGR_remove_notification_message_actions - * Purpose : Remove all actions to send a message owned by a particular owner - * Parameters : - * owner : owner of the trigger action - * Return Value : - * 0 : Success - * !0 : Some error - * Note : this only affect IPC notifcations (SE_MSG_NOTIFICATION) - */ +/** +* @brief Remove all notification message actions owned by a particular owner. +* +* This function removes all IPC notification message actions (SE_MSG_NOTIFICATION) that +* are owned by the specified owner. Typically called when a client disconnects. +* +* @param[in] owner - Owner of the trigger actions to remove. +* +* @return The status of the operation. +* @retval 0 Success. +* @retval Non-zero Some error. +* +* @note This only affects IPC notifications (SE_MSG_NOTIFICATION). +*/ int TRIGGER_MGR_remove_notification_message_actions(const token_t owner); -/* - * Procedure : TRIGGER_MGR_execute_trigger_actions - * Purpose : Execute all actions set for a trigger - * Parameters : - * trigger_id : The trigger id of the trigger upon which to execute actions - * name : The name of the data tuple that the trigger is on - * value : The value of the data tuple that the trigger is on - * source : The original source of this set - * tid : A Transaction id for notification messages - - * Return Value : - * 0 : Success - * !0 : Some error - */ +/** +* @brief Execute all actions set for a trigger. +* +* This function executes all registered actions associated with a trigger when the trigger's data tuple changes value. +* +* @param[in] trigger_id - The trigger ID of the trigger upon which to execute actions. +* @param[in] name - The name of the data tuple that the trigger is on. +* @param[in] value - The value of the data tuple that the trigger is on. +* @param[in] source - The original source of this set. +* @param[in] tid - A transaction ID for notification messages. +* +* @return The status of the operation. +* @retval 0 Success. +* @retval Non-zero Some error. +* +* @note This function is called by data manager while it has a mutex lock. DO NOT CALL ANY DATA_MGR functions. +*/ int TRIGGER_MGR_execute_trigger_actions(const int trigger_id, const char* const name, const char* const value, const int source, const int tid); + +/** +* @brief Execute all actions set for a trigger with binary data. +* +* This function executes all registered actions associated with a trigger when the trigger's +* data tuple changes value. This variant handles binary data values. +* +* @param[in] trigger_id - The trigger ID of the trigger upon which to execute actions. +* @param[in] name - The name of the data tuple that the trigger is on. +* @param[in] value - The binary value of the data tuple that the trigger is on. +* @param[in] value_length - The length of the binary value in bytes. +* @param[in] source - The original source of this set. +* @param[in] tid - A transaction ID for notification messages. +* +* @return The status of the operation. +* @retval 0 Success. +* @retval Non-zero Some error. +*/ int TRIGGER_MGR_execute_trigger_actions_data(const int trigger_id, const char* const name, const char* const value, const int value_length, const int source, const int tid); -/* - * Procedure : TRIGGER_MGR_get_cloned_action - * Purpose : Find the action given a trigger_id action_id - * Parameters : - * trigger_id : The trigger id of the trigger - * action_id : The action_id of the action - * in_action : Space to put the cloned action - * Return Value : - * 0 : Success - * !0 : Some error - * Notes : Caller must free the action using TRIGGER_MGR_free_cloned_action - */ +/** +* @brief Find and clone an action given a trigger_id and action_id. +* +* This function locates an action within a trigger and creates a copy of it in the provided +* structure. The caller must free the cloned action using TRIGGER_MGR_free_cloned_action. +* +* @param[in] trigger_id - The trigger ID of the trigger. +* @param[in] action_id - The action_id of the action. +* @param[out] in_action - A pointer to a trigger_action_t to put the action. +* +* @return The status of the operation. +* @retval 0 Success. +* @retval Non-zero Some error. +* +* @note Caller must free the action using TRIGGER_MGR_free_cloned_action. +*/ int TRIGGER_MGR_get_cloned_action(int trigger_id, int action_id, trigger_action_t *in_action); -/* - * Procedure : TRIGGER_MGR_free_cloned_action - * Purpose : Given an action free it - * Parameters : - * action : A pointer to a trigger_action_t clone to free - * Return Value : - * 0 : success - */ +/** +* @brief Free a cloned action. +* +* This function frees all memory associated with a cloned trigger_action_t structure +* that was obtained via TRIGGER_MGR_get_cloned_action. +* +* @param[in,out] action - A pointer to a trigger_action_t clone to free. +* +* @return The status of the operation. +* @retval 0 Success. +* +*/ int TRIGGER_MGR_free_cloned_action(trigger_action_t *action); -/* - * Procedure : TRIGGER_MGR_init - * Purpose : Initialize the Trigger Manager - * Parameters : - * Return Code : - * 0 : OK - * <0 : some error. - */ +/** +* @brief Initialize the Trigger Manager. +* +* This function initializes the trigger manager by setting up the global trigger list and preparing internal structures +* for managing triggers and actions. This must be called before any other trigger manager functions are used. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* @retval <0 Some error occurred. +* +*/ int TRIGGER_MGR_init(void); -/* - * Procedure : TRIGGER_MGR_deinit - * Purpose : Uninitialize the Trigger Manager - * Parameters : - * Return Code : - * 0 : OK - */ +/** +* @brief Uninitialize the Trigger Manager. +* +* This function cleans up the trigger manager by freeing all triggers, actions, and releasing allocated memory. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int TRIGGER_MGR_deinit(void); -#endif // __TRIGGER_MGR_H_ +#endif // __TRIGGER_MGR_H_ \ No newline at end of file diff --git a/source/test/apply_system_defaults/apply_system_defaults_test.h b/source/test/apply_system_defaults/apply_system_defaults_test.h index facdd087..93a96d3b 100644 --- a/source/test/apply_system_defaults/apply_system_defaults_test.h +++ b/source/test/apply_system_defaults/apply_system_defaults_test.h @@ -58,9 +58,47 @@ MessageBusMock * g_messagebusMock = nullptr; int syscfg_supported; int psm_supported; -extern "C" +extern "C" { +/** +* @brief Add parameters to the syscfg database. +* +* This function checks if specific parameters need to be added to the syscfg/PSM databases +* and adds them if they are not already present. +* +* @param[in] key - The parameter key to add to the database. +* @param[in] value - The value to associate with the key. +* +* @return None. +*/ void addInSysCfgdDB (char *key, char *value); + +/** +* @brief Update parameters in the syscfg database. +* +* This function updates existing parameters in the syscfg/PSM databases. +* +* @param[in] key - The parameter key to update in the database. +* @param[in] value - The new value to set for the key. +* +* @return None. +*/ void updateSysCfgdDB (char *key, char *value); + +/** +* @brief Compare partner JSON parameters between bootstrap and default configurations. +* +* This function compares partner parameters in the /etc default file with the /nvram bootstrap file to synchronize +* the configuration, updating the persistent records (psm/syscfg) as necessary. +* +* @param[in] partner_nvram_bs_obj - JSON object string from bootstrap configuration in nvram. +* @param[in] partner_etc_obj - JSON object string from default configuration in /etc. +* @param[in] PartnerID - The partner identifier string. +* +* @return The status of the comparison operation. +* @retval 0 Comparison successful and parameters may need updating. +* @retval -1 No comparison needed or error occurred. +* +*/ int compare_partner_json_param (char *partner_nvram_bs_obj, char *partner_etc_obj, char *PartnerID); } \ No newline at end of file diff --git a/source/test/service_dhcp/FopenMock.h b/source/test/service_dhcp/FopenMock.h index 27947456..941da341 100644 --- a/source/test/service_dhcp/FopenMock.h +++ b/source/test/service_dhcp/FopenMock.h @@ -25,11 +25,39 @@ class FopenMock { public: + /** + * @brief Mock method for fopen functionality. + * + * This mock method simulates the behavior of fopen, allowing unit tests to define + * expected behavior and return values for file opening operations. + * + * @param[in] filename - The name of the file to open. + * @param[in] mode - The mode string specifying how to open the file. + * + * @return Pointer to the FILE object. + * @retval FILE* Pointer to the opened file stream on success. + * @retval NULL if the operation fails. + * + */ MOCK_METHOD(FILE*, fopen_mock, (const char* filename, const char* mode), ()); }; extern FopenMock* g_fopenMock; +/** +* @brief Wrapper function for mocking fopen. +* +* This C-linkage function provides a mockable interface for the fopen standard library function. +* If g_fopenMock is set, it delegates to the mock object; otherwise, it calls the real fopen. +* +* @param[in] filename - The name of the file to open. +* @param[in] mode - The mode string specifying how to open the file. +* +* @return Pointer to the FILE object. +* @retval FILE* Pointer to the opened file stream on success. +* @retval NULL if the operation fails. +* +*/ extern "C" FILE* fopen_mock(const char* filename, const char* mode); #endif // FOPEN_MOCK_H \ No newline at end of file diff --git a/source/test/service_dhcp/service_dhcp_mock.h b/source/test/service_dhcp/service_dhcp_mock.h index d3bf6ad8..80a140f5 100644 --- a/source/test/service_dhcp/service_dhcp_mock.h +++ b/source/test/service_dhcp/service_dhcp_mock.h @@ -1,117 +1,482 @@ -/** -* Copyright 2024 Comcast Cable Communications Management, LLC -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -* -* SPDX-License-Identifier: Apache-2.0 -*/ -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include - -#define SERVICE_DHCP_JSON "/tmp/service_dhcp.json" -#define DEVICE_PROPS_FILE "/etc/device.properties" - -extern SyscfgMock* g_syscfgMock; -extern SecureWrapperMock* g_securewrapperMock; -extern SafecLibMock* g_safecLibMock; -extern utopiaMock* g_utopiaMock; -extern telemetryMock* g_telemetryMock; -extern SyseventMock* g_syseventMock; -extern PsmMock * g_psmMock; -extern MessageBusMock * g_messagebusMock; -extern AnscMemoryMock * g_anscMemoryMock; -extern LibnetMock * g_libnetMock; -extern FileIOMock * g_fileIOMock; - -using namespace std; -using namespace testing; -using ::testing::_; -using ::testing::Return; -using ::testing::SetArgPointee; -using ::testing::StrEq; -using ::testing::HasSubstr; -using ::testing::SetArrayArgument; -using std::experimental::filesystem::exists; -using ::testing::DoAll; - -extern "C" { -#include "syscfg.h" -#include "secure_wrapper.h" -#include "safec_lib.h" -#include -#include -#include "sysevent/sysevent.h" -#include "syscfg/syscfg.h" -#include "lan_handler.h" -#include "util.h" -#include -#include "print_uptime.h" -#include -#include "safec_lib_common.h" -#include "service_dhcp_server.h" -#include "dhcp_server_functions.h" -#include "service_ipv4.h" - -unsigned int mask2cidr(char *subnetMask); -int sysevent_syscfg_init(); -unsigned int countSetBits(int byte); -void subnet(char *ipv4Addr, char *ipv4Subnet, char *subnet); -void wait_till_end_state (char *process_to_wait); -BOOL compare_files(char *input_file1, char *input_file2); -void copy_command_output(FILE *fp, char *out, int len); -void print_file(char *to_print_file); -void remove_file(char *tb_removed_file); -void copy_file(char *input_file, char *target_file); -int executeCmd(char *cmd); -void get_device_props(); -void print_with_uptime(const char* input); -void _get_shell_output(FILE *fp, char *buf, int len); -int getValueFromDevicePropsFile(char *str, char **value); -int get_Pool_cnt(char arr[15][2],FILE *pipe); -void getRFC_Value(const char* dnsOption); -int dnsmasq_server_start(); -BOOL IsDhcpConfHasInterface(void); -void remove_config(int l3_inst); -void load_static_l3 (int l3_inst); -int isValidLANIP(const char* ipStr); -void UpdateConfigListintoConfFile(FILE *l_fLocal_Dhcp_ConfFile); -void AddConfList(char *confToken); -void UpdateConfList(char *confTok, int ct); -unsigned int isValidSubnetMask(char *subnetMask); -enum interface{ - ExistWithSameRange, - ExistWithDifferentRange, - NotExists -}; -enum interface IsInterfaceExists(char *confTok, char * confInf, int* inst); +/** +* Copyright 2024 Comcast Cable Communications Management, LLC +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +* +* SPDX-License-Identifier: Apache-2.0 +*/ +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#define SERVICE_DHCP_JSON "/tmp/service_dhcp.json" +#define DEVICE_PROPS_FILE "/etc/device.properties" + +extern SyscfgMock* g_syscfgMock; +extern SecureWrapperMock* g_securewrapperMock; +extern SafecLibMock* g_safecLibMock; +extern utopiaMock* g_utopiaMock; +extern telemetryMock* g_telemetryMock; +extern SyseventMock* g_syseventMock; +extern PsmMock * g_psmMock; +extern MessageBusMock * g_messagebusMock; +extern AnscMemoryMock * g_anscMemoryMock; +extern LibnetMock * g_libnetMock; +extern FileIOMock * g_fileIOMock; + +using namespace std; +using namespace testing; +using ::testing::_; +using ::testing::Return; +using ::testing::SetArgPointee; +using ::testing::StrEq; +using ::testing::HasSubstr; +using ::testing::SetArrayArgument; +using std::experimental::filesystem::exists; +using ::testing::DoAll; + +extern "C" { +#include "syscfg.h" +#include "secure_wrapper.h" +#include "safec_lib.h" +#include +#include +#include "sysevent/sysevent.h" +#include "syscfg/syscfg.h" +#include "lan_handler.h" +#include "util.h" +#include +#include "print_uptime.h" +#include +#include "safec_lib_common.h" +#include "service_dhcp_server.h" +#include "dhcp_server_functions.h" +#include "service_ipv4.h" + +/** +* @brief Convert a subnet mask to CIDR notation. +* +* This function converts an IPv4 subnet mask in dotted decimal notation to +* its equivalent CIDR (Classless Inter-Domain Routing) prefix length by counting +* the number of set bits in the subnet mask. +* +* @param[in] subnetMask - Pointer to a string containing the subnet mask in dotted decimal notation. +* \n The subnet mask must be in valid IPv4 format with continuous 1s starting from MSB. +* +* @return The CIDR prefix length. +* @retval 0-32 The number of set bits representing the network prefix length. +* +*/ +unsigned int mask2cidr(char *subnetMask); + +/** +* @brief Initialize sysevent and syscfg for the DHCP service. +* +* This function opens a connection to the sysevent daemon, initializes DBUS, +* and opens the ARM console log file for the service_dhcp component. +* +* @return The status of the initialization operation. +* @retval SUCCESS if both sysevent and DBUS initialization are successful. +* @retval ERROR if sysevent open fails or DBUS initialization fails. +* +*/ +int sysevent_syscfg_init(); + +/** +* @brief Count the number of set bits in a byte. +* +* This function counts the number of bits set to 1 in a given byte value. +* It validates that the byte represents a valid subnet mask byte before counting. +* +* @param[in] byte - The byte value to count set bits in. +* \n Must be a valid subnet byte or 0. +* +* @return The number of set bits in the byte. +* @retval 0-8 The count of bits set to 1 in the byte. +* @retval 0 If the byte is not a valid subnet mask byte. +* +*/ +unsigned int countSetBits(int byte); + +/** +* @brief Calculate the network subnet from an IPv4 address and subnet mask. +* +* This function performs a bitwise AND operation between an IPv4 address and +* its subnet mask to derive the network subnet address. +* +* @param[in] ipv4Addr - Pointer to a string containing the IPv4 address in dotted decimal notation. +* @param[in] ipv4Subnet - Pointer to a string containing the subnet mask in dotted decimal notation. +* @param[out] subnet - Pointer to a buffer where the calculated subnet address will be stored. +* \n The buffer should be at least 16 bytes to hold the subnet address string. +* +* @return None +* +*/ +void subnet(char *ipv4Addr, char *ipv4Subnet, char *subnet); + +/** +* @brief Wait until a process reaches an end state (not starting/stopping). +* +* This function polls the sysevent status of a specified process up to 9 times, +* waiting 1 second between attempts, until the process is no longer in a transitional state. +* +* @param[in] process_to_wait - Pointer to a string containing the process name to wait for. +* \n The function will check -status sysevent. +* +* @return None +* +*/ +void wait_till_end_state (char *process_to_wait); + +/** +* @brief Compare two files line by line for equality. +* +* This function reads two files and compares them line by line to determine +* if they are identical. +* +* @param[in] input_file1 - Pointer to a string containing the path to the first file. +* @param[in] input_file2 - Pointer to a string containing the path to the second file. +* +* @return Boolean indicating whether the files are identical. +* @retval TRUE if the two files are identical (all lines match). +* @retval FALSE if the files differ or if either file cannot be opened. +* +*/ +BOOL compare_files(char *input_file1, char *input_file2); + +/** +* @brief Copy command output from a file pointer to a buffer. +* +* This function reads one line from the provided file pointer and copies it +* to the output buffer, removing any trailing newline character. +* +* @param[in] fp - File pointer to read the command output from. +* @param[out] out - Pointer to a buffer where the output will be stored. +* @param[in] len - Maximum length of the output buffer. +* +* @return None. +* +*/ +void copy_command_output(FILE *fp, char *out, int len); + +/** +* @brief Print the contents of a file to the ARM console log. +* +* This function opens a file and writes all its contents line by line +* to the ARM console log file. +* +* @param[in] to_print_file - Pointer to a string containing the path to the file to be printed. +* +* @return None +* +*/ +void print_file(char *to_print_file); + +/** +* @brief Remove a file from the filesystem. +* +* This function deletes the specified file and logs an error message +* if the removal fails. +* +* @param[in] tb_removed_file - Pointer to a string containing the path to the file to be removed. +* +* @return None +* +*/ +void remove_file(char *tb_removed_file); + +/** +* @brief Copy the contents of one file to another. +* +* This function reads all lines from the input file and writes them to the target file. +* The target file is opened in write mode, overwriting any existing content. +* +* @param[in] input_file - Pointer to a string containing the path to the source file. +* @param[in] target_file - Pointer to a string containing the path to the destination file. +* +* @return None +* +*/ +void copy_file(char *input_file, char *target_file); + +/** +* @brief Execute a shell command using the system() function. +* +* This function executes the provided shell command and logs an error +* if the command execution fails. +* +* @param[in] cmd - Pointer to a string containing the command to execute. +* +* @return The status of the command execution. +* @retval 0 if the command executed successfully or errno is ECHILD. +* @retval non-zero The system() return value if execution failed. +* +*/ +int executeCmd(char *cmd); + +/** +* @brief Read device properties from the device properties file. +* +* This function parses the device properties file (DEVICE_PROPS_FILE) and extracts +* values for BOX_TYPE, XDNS_ENABLE, MIG_CHECK, and ATOM_ARPING_IP into global variables. +* +* @return None +* +*/ +void get_device_props(); + +/** +* @brief Print a message with system uptime and local time. +* +* This function retrieves the current system uptime and local time, +* then prints the input message along with formatted time information to the ARM console log. +* +* @param[in] input - Pointer to a string containing the message to be printed. +* +* @return None +* +*/ +void print_with_uptime(const char* input); + +/** +* @brief Get shell command output from a file pointer. +* +* This function reads output from a file pointer, removes trailing newlines, and closes +* the file pointer using v_secure_pclose(). +* +* @param[in] fp - File pointer to read output from. +* @param[out] buf - Pointer to a buffer where the output will be stored. +* @param[in] len - Maximum length of the output buffer. +* +* @return None +* +*/ +void _get_shell_output(FILE *fp, char *buf, int len); + +/** +* @brief Get a value from the device properties file. +* +* This function searches the device properties file for a specified key and +* returns the corresponding value. +* +* @param[in] str - Pointer to a string containing the key to search for. +* @param[out] value - Pointer to a pointer that will point to the value string in the buffer. +* \n The pointer will reference data in a static buffer. +* +* @return The status of the operation. +* @retval 0 if the key was found and value was set successfully. +* @retval -1 if the key was not found or the file could not be opened. +* +*/ +int getValueFromDevicePropsFile(char *str, char **value); + +/** +* @brief Get pool count from a pipe stream. +* +* This function reads pool identifiers from a pipe stream and stores them in an array, +* returning the total count of valid pool entries found. +* +* @param[out] arr - Two-dimensional array to store pool identifiers (up to 15 entries of 2 characters each). +* @param[in] pipe - File pointer to the pipe stream to read from. +* +* @return The number of valid pool entries found. +* @retval -1 if the pipe is NULL. +* @retval 0-15 The count of valid pool identifiers read from the pipe. +* +*/ +int get_Pool_cnt(char arr[15][2],FILE *pipe); + +/** +* @brief Get DNS strict order RFC value from syscfg. +* +* This function checks the DNSStrictOrder configuration and sets the dnsOption +* parameter to " -o " if DNS strict order is enabled. +* +* @param[out] dnsOption - Pointer to a buffer where the DNS option string will be stored. +* \n Will be set to " -o " if DNSStrictOrder is "true", otherwise remains unchanged. +* +* @return None +* +*/ +void getRFC_Value(const char* dnsOption); + +/** +* @brief Start the dnsmasq DNS/DHCP server. +* +* This function constructs the appropriate dnsmasq command line based on +* device configuration (XDNS, DNSSEC, model type) and executes it. +* +* @return The status of the dnsmasq server start operation. +* @retval 0 if dnsmasq started successfully. +* @retval non-zero if the command execution failed. +* +*/ +int dnsmasq_server_start(); + +/** +* @brief Check if the DHCP configuration file has any interface defined. +* +* This function scans the dnsmasq configuration file (DHCP_CONF) to determine +* if it contains at least one "interface=" directive. +* +* @return Boolean indicating whether an interface is defined. +* @retval TRUE if the DHCP configuration file contains at least one interface directive. +* @retval FALSE if no interface directive is found or the file cannot be opened. +* +*/ +BOOL IsDhcpConfHasInterface(void); + +/** +* @brief Remove IPv4 configuration for a Layer 3 network instance. +* +* This function removes IP address, routing rules, and routes associated with +* the specified L3 network instance. It also stops UPNP services if removing +* configuration for the LAN interface. +* +* @param[in] l3_inst - The Layer 3 network instance number. +* \n Typically ranges from 1-5 for different network segments. +* +* @return None +* +*/ +void remove_config(int l3_inst); + +/** +* @brief Load static IPv4 configuration for a Layer 3 network instance. +* +* This function retrieves static IPv4 address and subnet mask from PSM database +* and applies the configuration to the specified L3 network instance. +* +* @param[in] l3_inst - The Layer 3 network instance number. +* \n Typically ranges from 1-5 for different network segments. +* +* @return None +* +*/ +void load_static_l3 (int l3_inst); + +/** +* @brief Validate if an IP address is a valid private LAN IP. +* +* This function checks if the provided IP address is a valid IPv4 address +* and falls within private IP address ranges (10.x.x.x, 172.16-31.x.x, 192.168.x.x). +* +* @param[in] ipStr - Pointer to a string containing the IP address to validate. +* +* @return Status indicating whether the IP is a valid LAN IP. +* @retval 0 if the IP address is invalid or not in a private LAN range. +* @retval 1 if the IP address is valid and within a private LAN range. +* +*/ +int isValidLANIP(const char* ipStr); + +/** +* @brief Write dynamic DHCP configuration list to the configuration file. +* +* This function reads all dynamic DHCP configuration changes from sysevent +* and writes them to the provided DHCP configuration file. +* +* @param[in] l_fLocal_Dhcp_ConfFile - File pointer to the DHCP configuration file. +* +* @return None +* +*/ +void UpdateConfigListintoConfFile(FILE *l_fLocal_Dhcp_ConfFile); + +/** +* @brief Add a new configuration entry to the dynamic DHCP configuration list. +* +* This function adds a new DHCP configuration token to sysevent storage and +* increments the configuration change counter. +* +* @param[in] confToken - Pointer to a string containing the configuration token to add. +* \n Format: "interface=|dhcp-range=" +* +* @return None +* +*/ +void AddConfList(char *confToken); + +/** +* @brief Update an existing configuration entry in the dynamic DHCP configuration list. +* +* This function updates a specific DHCP configuration entry identified by its index. +* +* @param[in] confTok - Pointer to a string containing the configuration token to update. +* \n Format: "interface=|dhcp-range=" +* @param[in] ct - The index of the configuration entry to update (1-based). +* +* @return None +* +*/ +void UpdateConfList(char *confTok, int ct); + +/** +* @brief Validate if a string represents a valid subnet mask. +* +* This function validates that a subnet mask has the correct format and structure, +* ensuring continuous 1s from MSB followed by continuous 0s in the host part. +* +* @param[in] subnetMask - Pointer to a string containing the subnet mask in dotted decimal notation. +* +* @return Status indicating whether the subnet mask is valid. +* @retval 0 if the subnet mask is invalid. +* @retval 1 if the subnet mask is valid. +* +*/ +unsigned int isValidSubnetMask(char *subnetMask); + +enum interface{ + ExistWithSameRange, + ExistWithDifferentRange, + NotExists +}; + +/** +* @brief Check if an interface exists in the dynamic DHCP configuration list. +* +* This function searches the dynamic DHCP configuration list to determine if +* a specified interface exists and whether its configuration matches. +* +* @param[in] confTok - Pointer to a string containing the configuration token to check. +* \n Format: "interface=|dhcp-range=" +* @param[in] confInf - Pointer to a string containing the interface name to search for. +* @param[out] inst - Pointer to an integer where the matching instance index will be stored. +* +* @return Enumeration value indicating the interface existence status. +* @retval NotExists if dhcp_conf_change_counter is 0 or interface not found. +* @retval ExistWithSameRange if interface exists with matching configuration. +* @retval ExistWithDifferentRange if interface exists with different configuration. +* +*/ +enum interface IsInterfaceExists(char *confTok, char * confInf, int* inst); } \ No newline at end of file diff --git a/source/test/service_ipv6/service_ipv6_mock.h b/source/test/service_ipv6/service_ipv6_mock.h index a8d9b5aa..b728775f 100644 --- a/source/test/service_ipv6/service_ipv6_mock.h +++ b/source/test/service_ipv6/service_ipv6_mock.h @@ -86,7 +86,40 @@ typedef struct dhcpv6s_cfg { int pool_num; int server_type; } dhcpv6s_cfg_t; + +/** +* @brief Get the DHCPv6 server configuration. +* +* This function retrieves DHCPv6 server configuration parameters from syscfg, +* including server enable status, pool number, and server type. +* +* @param[out] cfg - Pointer to a dhcpv6s_cfg_t structure where the configuration will be stored. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ int get_dhcpv6s_conf(dhcpv6s_cfg_t *cfg); + +/** +* @brief Extract IPv6 prefix value and length from a prefix string. +* +* This function parses an IPv6 prefix string in CIDR notation and extracts +* the prefix value and prefix length separately. +* +* @param[in] prefix - Pointer to a string containing the IPv6 prefix in CIDR notation. +* \n Format: "/" +* @param[out] value - Pointer to a buffer where the IPv6 prefix value will be stored (without /length). +* \n Can be NULL if only prefix_len is needed. +* @param[in] val_len - Maximum length of the value buffer. +* @param[out] prefix_len - Pointer to an unsigned int where the prefix length will be stored. +* \n Can be NULL if only value is needed. +* +* @return The status of the operation. +* @retval 0 if the prefix was successfully parsed. +* @retval -1 if the prefix format is invalid (no '/' found). +* +*/ int get_prefix_info(const char *prefix, char *value, unsigned int val_len, unsigned int *prefix_len); enum tp_mod { TPMOD_UNKNOWN, @@ -111,23 +144,261 @@ typedef struct dhcpv6s_cfg { enum tp_mod tpmod; }; - +/** +* @brief Get the prefix delegation pool configuration. +* +* This function retrieves the prefix delegation pool parameters from sysevent, +* including start/end addresses and prefix lengths. +* +* @param[in] si6 - Pointer to the serv_ipv6 structure containing sysevent connection. +* @param[out] pool - Pointer to a pd_pool_t structure where the pool configuration will be stored. +* +* @return The status of the operation. +* @retval 0 if all required sysevent values were successfully retrieved. +* @retval -1 if any required sysevent value is missing or empty. +* +*/ int get_pd_pool(struct serv_ipv6 *si6, pd_pool_t *pool); + +/** +* @brief Initialize the IPv6 service. +* +* This function initializes the IPv6 service by opening sysevent connection, +* initializing DBUS, reading configuration, and checking IPv6 enablement status. +* +* @param[in,out] si6 - Pointer to the serv_ipv6 structure to initialize. +* +* @return The status of the operation. +* @retval 0 if initialization was successful. +* @retval -1 if sysevent open failed, IPv6 is disabled, or MSO prefix is not available. +* +*/ int serv_ipv6_init(struct serv_ipv6 *si6); + +/** +* @brief Restart the IPv6 service. +* +* This function stops and then starts the IPv6 service. +* +* @param[in] si6 - Pointer to the serv_ipv6 structure. +* +* @return The status of the start operation. +* @retval 0 if service was successfully restarted. +* @retval -1 if the start operation failed. +* +*/ int serv_ipv6_restart(struct serv_ipv6 *si6); + +/** +* @brief Start the IPv6 service. +* +* This function starts the IPv6 service by dividing prefixes, assigning LAN addresses, +* updating MTU, and starting the DHCPv6 server. +* +* @param[in] si6 - Pointer to the serv_ipv6 structure. +* +* @return The status of the operation. +* @retval 0 if the service started successfully. +* @retval -1 if service cannot start, WAN is not ready, or any operation failed. +* +*/ int serv_ipv6_start(struct serv_ipv6 *si6); + +/** +* @brief Stop the IPv6 service. +* +* This function stops the IPv6 service by stopping the DHCPv6 server +* and unsetting LAN IPv6 addresses. +* +* @param[in] si6 - Pointer to the serv_ipv6 structure. +* +* @return The status of the operation. +* @retval 0 if the service stopped successfully. +* @retval -1 if service cannot stop or any operation failed. +* +*/ int serv_ipv6_stop(struct serv_ipv6 *si6); + +/** +* @brief Restart the DHCPv6 server. +* +* This function stops and then starts the DHCPv6 server (dibbler). +* +* @param[in] si6 - Pointer to the serv_ipv6 structure. +* +* @return The status of the start operation. +* @retval 0 if DHCPv6 server was successfully restarted. +* @retval -1 if the start operation failed. +* +*/ int dhcpv6s_restart(struct serv_ipv6 *si6); + +/** +* @brief Stop the DHCPv6 server. +* +* This function stops the DHCPv6 server daemon (dibbler). +* +* @param[in] si6 - Pointer to the serv_ipv6 structure. +* +* @return The status of the operation. +* @retval 0 if the DHCPv6 server was successfully stopped. +* @retval -1 if the stop operation failed. +* +*/ int dhcpv6s_stop(struct serv_ipv6 *si6); + +/** +* @brief Start the DHCPv6 server. +* +* This function generates the dibbler configuration file and starts the DHCPv6 server. +* +* @param[in] si6 - Pointer to the serv_ipv6 structure. +* +* @return The status of the operation. +* @retval 0 if the DHCPv6 server started successfully or is disabled. +* @retval -1 if dibbler configuration generation failed. +* +*/ int dhcpv6s_start(struct serv_ipv6 *si6); + +/** +* @brief Format dibbler options by replacing spaces with commas. +* +* This function modifies a dibbler option string by replacing all space characters +* with commas, which is the format required by the dibbler configuration. +* +* @param[in,out] option - Pointer to a string containing the option to format. +* \n The string is modified in place. +* +* @return The status of the operation. +* @retval 0 if the option was successfully formatted. +* @retval -1 if the option pointer is NULL. +* +*/ int format_dibbler_option(char *option); + +/** +* @brief Get LAN ULA (Unique Local Address) enablement status. +* +* This function retrieves the LAN ULA enablement flag from the PSM database. +* +* @param[out] ula_enable - Pointer to an integer where the ULA enable status will be stored. +* \n Set to TRUE if ULA is enabled, FALSE otherwise. +* +* @return The status of the operation. +* @retval 0 if the ULA enable status was successfully retrieved. +* @retval -1 if PSM read failed. +* +*/ int getLanUlaInfo(int *ula_enable); + +/** +* @brief Unset IPv6 addresses from LAN interfaces. +* +* This function removes IPv6 addresses from all active LAN interfaces and +* clears related sysevent parameters. +* +* @param[in] si6 - Pointer to the serv_ipv6 structure. +* +* @return The status of the operation. +* @retval 0 if IPv6 addresses were successfully removed from all interfaces. +* @retval -1 if operation failed. +* +*/ int lan_addr6_unset(struct serv_ipv6 *si6); + +/** +* @brief Assign IPv6 addresses to LAN interfaces. +* +* This function divides the MSO-delegated prefix, assigns IPv6 addresses to LAN +* interfaces based on their interface-prefixes, and configures interface parameters. +* +* @param[in] si6 - Pointer to the serv_ipv6 structure. +* +* @return The status of the operation. +* @retval 0 if IPv6 addresses were successfully assigned to all interfaces. +* @retval -1 if prefix division failed or no active LAN interfaces found. +* +*/ int lan_addr6_set(struct serv_ipv6 *si6); + +/** +* @brief Update MTU for all enabled IPv6 L3 instances. +* +* This function iterates through all enabled Layer 3 IPv6 network instances +* and sets the appropriate MTU value for each interface. +* +* @return None +* +*/ void update_mtu(void); + +/** +* @brief Report prefix assignment failure for all LAN interfaces. +* +* This function reports that IPv6 prefix assignment completely failed by +* invoking the no-prefix reporting for all active LAN interfaces. +* +* @param[in] si6 - Pointer to the serv_ipv6 structure. +* +* @return None +* +*/ void report_no_lan_prefixes(struct serv_ipv6 *si6); + +/** +* @brief Compute a global IPv6 address based on a /64 interface prefix. +* +* This function generates a global IPv6 address by combining a /64 prefix with +* an EUI-64 identifier derived from the interface's MAC address. +* +* @param[in] prefix - Pointer to a string containing the IPv6 prefix in CIDR notation (e.g., "2001:db8::/64"). +* @param[in] if_name - Pointer to a string containing the interface name. +* @param[out] ipv6_addr - Pointer to a buffer where the computed IPv6 address will be stored. +* @param[in] addr_len - Maximum length of the ipv6_addr buffer. +* +* @return The status of the operation. +* @retval 0 if the global IPv6 address was successfully computed. +* @retval -1 if the prefix format is invalid, prefix length > 64, MAC address retrieval failed, or invalid format. +* +*/ int compute_global_ip(char *prefix, char *if_name, char *ipv6_addr, unsigned int addr_len); + +/** +* @brief Get the hardware (MAC) address of a network interface. +* +* This function retrieves the MAC address of the specified network interface +* using ioctl system call. +* +* @param[in] ifname - Pointer to a string containing the interface name. +* @param[out] mac - Pointer to a buffer where the MAC address will be stored. +* \n Format: "XX:XX:XX:XX:XX:XX" +* \n Buffer must be at least 18 bytes ("00:00:00:00:00:00" + null terminator). +* @param[in] size - Size of the mac buffer. +* +* @return The status of the operation. +* @retval 0 if the MAC address was successfully retrieved. +* @retval -1 if parameters are invalid, socket creation failed, or ioctl failed. +* +*/ int iface_get_hwaddr(const char *ifname, char *mac, size_t size); + +/** +* @brief Stop a daemon process. +* +* This function stops a daemon by reading its PID from a file or searching +* by process name, sending SIGTERM, and removing the PID file. +* +* @param[in] pid_file - Pointer to a string containing the path to the PID file. +* \n Can be NULL if only prog name is provided. +* @param[in] prog - Pointer to a string containing the process/program name. +* \n Can be NULL if only pid_file is provided. +* +* @return The status of the operation. +* @retval 0 on success +* @retval -1 if both pid_file and prog are NULL. +* +*/ int daemon_stop(const char *pid_file, const char *prog); } diff --git a/source/test/service_wan/service_wan_mock.h b/source/test/service_wan/service_wan_mock.h index 8a21c722..fb64809b 100755 --- a/source/test/service_wan/service_wan_mock.h +++ b/source/test/service_wan/service_wan_mock.h @@ -1,119 +1,519 @@ -/** -* Copyright 2024 Comcast Cable Communications Management, LLC -* -* Licensed under the Apache License, Version 2.0 (the "License"); -* you may not use this file except in compliance with the License. -* You may obtain a copy of the License at -* -* http://www.apache.org/licenses/LICENSE-2.0 -* -* Unless required by applicable law or agreed to in writing, software -* distributed under the License is distributed on an "AS IS" BASIS, -* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -* See the License for the specific language governing permissions and -* limitations under the License. -* -* SPDX-License-Identifier: Apache-2.0 -*/ - -#include -#include -#include -#include -#include -#include "print_uptime.h" -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#include -#define IFNAMSIZ 16 -#define SW_PROT_TIMO 675 -#define RESOLV_CONF_FILE "resolv.conf" -#define VENDOR_SPEC_FILE "udhcpc.txt" -#define VENDOR_OPTIONS_LENGTH 100 - -using namespace std; -using namespace testing; -using ::testing::_; -using ::testing::Return; -using ::testing::SetArgPointee; -using ::testing::StrEq; -using ::testing::SetArrayArgument; - -SyscfgMock* g_syscfgMock = nullptr; -SecureWrapperMock* g_securewrapperMock = nullptr; -SafecLibMock* g_safecLibMock = nullptr; -utopiaMock* g_utopiaMock = nullptr; -telemetryMock* g_telemetryMock = nullptr; -SyseventMock* g_syseventMock = nullptr; -PsmMock * g_psmMock = nullptr; -MessageBusMock * g_messagebusMock = nullptr; -AnscMemoryMock * g_anscMemoryMock = nullptr; -FileIOMock * g_fileIOMock = nullptr; -rdkloggerMock * g_rdkloggerMock = nullptr; - -enum wan_prot { - WAN_PROT_DHCP, - WAN_PROT_STATIC, -}; - -enum wan_rt_mod { - WAN_RTMOD_UNKNOW, - WAN_RTMOD_IPV4, // COSA_DML_DEVICE_MODE_Ipv4 - 1 - WAN_RTMOD_IPV6, // COSA_DML_DEVICE_MODE_Ipv6 - 1 - WAN_RTMOD_DS, // COSA_DML_DEVICE_MODE_Dualstack - 1 -}; -struct serv_wan { - int sefd; - int setok; - char ifname[IFNAMSIZ]; - enum wan_rt_mod rtmod; - enum wan_prot prot; - int timo; -}; - -extern "C" -{ -#include "util.h" -void usage(void); -int serv_wan_term(struct serv_wan *sw); -int serv_wan_init(struct serv_wan *sw, const char *ifname, const char *prot); -int wan_static_stop_v6(struct serv_wan *sw); -int wan_static_start_v6(struct serv_wan *sw); -int resolv_static_deconfig(struct serv_wan *sw); -int resolv_static_config(struct serv_wan *sw); -int wan_static_stop(struct serv_wan *sw); -int wan_static_start(struct serv_wan *sw); -int Getdhcpcpidfile(char *pidfile,int size ); -int wan_dhcp_renew(struct serv_wan *sw); -int dhcp_stop(const char* ifname); -int route_config(const char *ifname); -int route_config_v6(const char *ifname); -int route_deconfig_v6(const char *ifname); -int checkFileExists(const char *fname); -int route_deconfig(const char *ifname); -int wan_iface_down(struct serv_wan *sw); -int wan_iface_up(struct serv_wan *sw); -int wan_dhcp_release(struct serv_wan *sw); -int wan_dhcp_stop(struct serv_wan *sw); -int wan_addr_unset(struct serv_wan *sw); -int dhcp_parse_vendor_info( char *options, const int length, char *ethWanMode ); -int dhcp_start(struct serv_wan *sw) ; -int wan_start(struct serv_wan *sw); -int wan_stop(struct serv_wan *sw); -int wan_restart(struct serv_wan *sw); -int wan_dhcp_start(struct serv_wan *sw); -int wan_addr_set(struct serv_wan *sw); -int wan_dhcp_restart(struct serv_wan *sw); -FILE* logfptr; +/** +* Copyright 2024 Comcast Cable Communications Management, LLC +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +* +* SPDX-License-Identifier: Apache-2.0 +*/ + +#include +#include +#include +#include +#include +#include "print_uptime.h" +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#define IFNAMSIZ 16 +#define SW_PROT_TIMO 675 +#define RESOLV_CONF_FILE "resolv.conf" +#define VENDOR_SPEC_FILE "udhcpc.txt" +#define VENDOR_OPTIONS_LENGTH 100 + +using namespace std; +using namespace testing; +using ::testing::_; +using ::testing::Return; +using ::testing::SetArgPointee; +using ::testing::StrEq; +using ::testing::SetArrayArgument; + +SyscfgMock* g_syscfgMock = nullptr; +SecureWrapperMock* g_securewrapperMock = nullptr; +SafecLibMock* g_safecLibMock = nullptr; +utopiaMock* g_utopiaMock = nullptr; +telemetryMock* g_telemetryMock = nullptr; +SyseventMock* g_syseventMock = nullptr; +PsmMock * g_psmMock = nullptr; +MessageBusMock * g_messagebusMock = nullptr; +AnscMemoryMock * g_anscMemoryMock = nullptr; +FileIOMock * g_fileIOMock = nullptr; +rdkloggerMock * g_rdkloggerMock = nullptr; + +enum wan_prot { + WAN_PROT_DHCP, + WAN_PROT_STATIC, +}; + +enum wan_rt_mod { + WAN_RTMOD_UNKNOW, + WAN_RTMOD_IPV4, // COSA_DML_DEVICE_MODE_Ipv4 - 1 + WAN_RTMOD_IPV6, // COSA_DML_DEVICE_MODE_Ipv6 - 1 + WAN_RTMOD_DS, // COSA_DML_DEVICE_MODE_Dualstack - 1 +}; +struct serv_wan { + int sefd; + int setok; + char ifname[IFNAMSIZ]; + enum wan_rt_mod rtmod; + enum wan_prot prot; + int timo; +}; + +extern "C" +{ +#include "util.h" + +/** +* @brief Display usage information for the service_wan utility. +* +* This function prints command-line usage information and available commands +* to the standard output. +* +* @return None +* +*/ +void usage(void); + +/** +* @brief Terminate the WAN service. +* +* This function closes the sysevent connection for the WAN service. +* +* @param[in] sw - Pointer to the serv_wan structure. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ +int serv_wan_term(struct serv_wan *sw); + +/** +* @brief Initialize the WAN service. +* +* This function initializes the WAN service by opening sysevent connection, +* setting interface name, protocol, routing mode, and timeout. +* +* @param[in,out] sw - Pointer to the serv_wan structure to initialize. +* @param[in] ifname - Pointer to a string containing the WAN interface name. +* @param[in] prot - Pointer to a string containing the protocol type. +* +* @return The status of the operation. +* @retval 0 if initialization was successful. +* @retval -1 if sysevent open failed or invalid protocol specified. +* +*/ +int serv_wan_init(struct serv_wan *sw, const char *ifname, const char *prot); + +/** +* @brief Stop static IPv6 WAN configuration. +* +* This function stops static IPv6 WAN service by deconfiguring routes +* and unsetting static IPv6 resolv configuration. +* +* @param[in] sw - Pointer to the serv_wan structure. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval -1 if operation failed. +* +*/ +int wan_static_stop_v6(struct serv_wan *sw); + +/** +* @brief Start static IPv6 WAN configuration. +* +* This function starts static IPv6 WAN service by configuring routes +* and setting static IPv6 resolv configuration. +* +* @param[in] sw - Pointer to the serv_wan structure. +* +* @return The status of the operation. +* @retval 0 if configuration was successful. +* @retval -1 if any operation failed. +* +*/ +int wan_static_start_v6(struct serv_wan *sw); + +/** +* @brief Deconfigure static resolv.conf. +* +* This function removes DNS nameserver entries from /etc/resolv.conf +* for static WAN configuration. +* +* @param[in] sw - Pointer to the serv_wan structure. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval -1 if operation failed. +* +*/ +int resolv_static_deconfig(struct serv_wan *sw); + +/** +* @brief Configure static resolv.conf. +* +* This function writes DNS nameserver entries to /etc/resolv.conf +* for static WAN configuration. +* +* @param[in] sw - Pointer to the serv_wan structure. +* +* @return The status of the operation. +* @retval 0 if configuration was successful. +* @retval -1 if resolv.conf could not be opened. +* +*/ +int resolv_static_config(struct serv_wan *sw); + +/** +* @brief Stop static IPv4 WAN configuration. +* +* This function stops static IPv4 WAN service by deconfiguring IPv6 (if enabled), +* unsetting WAN address, bringing interface down, and clearing sysevent status. +* +* @param[in] sw - Pointer to the serv_wan structure. +* +* @return The status of the operation. +* @retval 0 on success +* +*/ +int wan_static_stop(struct serv_wan *sw); + +/** +* @brief Start static IPv4 WAN configuration. +* +* This function starts static IPv4 WAN service by bringing interface up, +* setting WAN address, and configuring IPv6 (if enabled). +* +* @param[in] sw - Pointer to the serv_wan structure. +* +* @return The status of the operation. +* @retval 0 if configuration was successful. +* @retval -1 if any operation failed. +* +*/ +int wan_static_start(struct serv_wan *sw); + +/** +* @brief Get the DHCP client PID file path. +* +* This function determines and returns the appropriate DHCP client PID file path +* based on platform and configuration. +* +* @param[out] pidfile - Pointer to a buffer where the PID file path will be stored. +* @param[in] size - Size of the pidfile buffer. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ +int Getdhcpcpidfile(char *pidfile,int size ); + +/** +* @brief Trigger DHCP renew for WAN interface. +* +* This function sends SIGUSR1 signal to the DHCP client to trigger +* lease renewal. +* +* @param[in] sw - Pointer to the serv_wan structure. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ +int wan_dhcp_renew(struct serv_wan *sw); + +/** +* @brief Stop the DHCP client. +* +* This function stops the DHCP client by sending SIGUSR2 (release) and SIGTERM, +* then removes the PID file. +* +* @param[in] ifname - Pointer to a string containing the interface name. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ +int dhcp_stop(const char* ifname); + +/** +* @brief Configure IPv4 routing rules for WAN interface. +* +* This function adds IP routing rules for the WAN interface to route traffic +* through appropriate routing tables. +* +* @param[in] ifname - Pointer to a string containing the interface name. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ +int route_config(const char *ifname); + +/** +* @brief Configure IPv6 routing rules for WAN interface. +* +* This function adds IPv6 routing rules for the WAN interface to route traffic +* through appropriate routing tables. +* +* @param[in] ifname - Pointer to a string containing the interface name. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ +int route_config_v6(const char *ifname); + +/** +* @brief Deconfigure IPv6 routing rules for WAN interface. +* +* This function removes IPv6 routing rules for the WAN interface. +* +* @param[in] ifname - Pointer to a string containing the interface name. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ +int route_deconfig_v6(const char *ifname); + +/** +* @brief Check if a file exists. +* +* This function checks whether a specified file exists in the filesystem. +* +* @param[in] fname - Pointer to a string containing the file path to check. +* +* @return The file existence status. +* @retval 1 if the file exists. +* @retval 0 if the file does not exist. +* +*/ +int checkFileExists(const char *fname); + +/** +* @brief Deconfigure IPv4 routing rules for WAN interface. +* +* This function removes IP routing rules for the WAN interface. +* +* @param[in] ifname - Pointer to a string containing the interface name. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ +int route_deconfig(const char *ifname); + +/** +* @brief Bring WAN interface down. +* +* This function brings down the WAN interface. +* +* @param[in] sw - Pointer to the serv_wan structure. +* +* @return The status of the operation. +* @retval 0 if the interface was successfully brought down. +* @retval -1 if the operation failed. +* +*/ +int wan_iface_down(struct serv_wan *sw); + +/** +* @brief Bring WAN interface up. +* +* This function brings up the WAN interface, configures IPv6 settings, +* and sets MTU. +* +* @param[in] sw - Pointer to the serv_wan structure. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ +int wan_iface_up(struct serv_wan *sw); + +/** +* @brief Release DHCP lease for WAN interface. +* +* This function sends SIGUSR2 signal to the DHCP client to trigger +* lease release without terminating the client. +* +* @param[in] sw - Pointer to the serv_wan structure. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval -1 if operation failed. +* +*/ +int wan_dhcp_release(struct serv_wan *sw); + +/** +* @brief Stop WAN DHCP client service. +* +* This function stops the DHCP client and clears WAN status. +* +* @param[in] sw - Pointer to the serv_wan structure. +* +* @return The status of the operation. +* @retval 0 on success. +* +*/ +int wan_dhcp_stop(struct serv_wan *sw); + +/** +* @brief Unset WAN address and clear sysevent parameters. +* +* This function removes the WAN IP address from the interface and +* clears related sysevent variables. +* +* @param[in] sw - Pointer to the serv_wan structure. +* +* @return The status of the operation. +* @retval 0 on success. +* @retval -1 if operation failed. +* +*/ +int wan_addr_unset(struct serv_wan *sw); + +/** +* @brief Parse vendor-specific DHCP options from file. +* +* This function reads and parses vendor-specific DHCP options from +* a configuration file and formats them as DHCP option 43. +* +* @param[out] options - Pointer to a buffer where the formatted options will be stored. +* @param[in] length - Maximum length of the options buffer. +* @param[in] ethWanMode - Pointer to a string indicating Ethernet WAN mode. +* +* @return The status of the operation. +* @retval 0 if options were successfully parsed. +* @retval -1 if file cannot be opened, parsing error, or buffer overflow. +* +*/ +int dhcp_parse_vendor_info( char *options, const int length, char *ethWanMode ); + +/** +* @brief Start DHCP client for WAN interface. +* +* This function starts the DHCP client on the WAN interface with vendor-specific options. +* +* @param[in] sw - Pointer to the serv_wan structure. +* +* @return The status of the operation. +* @retval 0 if DHCP client started successfully. +* @retval -1 if operation failed. +* +*/ +int dhcp_start(struct serv_wan *sw) ; + +/** +* @brief Start WAN service. +* +* This function starts the WAN service by initializing interfaces, starting +* protocol services, and configuring firewall and routing. +* +* @param[in] sw - Pointer to the serv_wan structure. +* +* @return The status of the operation. +* @retval 0 if WAN service started successfully. +* @retval -1 if any operation failed. +* +*/ +int wan_start(struct serv_wan *sw); + +/** +* @brief Stop WAN service. +* +* This function stops the WAN service by stopping protocol services, +* unsetting addresses, and bringing down the interface. +* +* @param[in] sw - Pointer to the serv_wan structure. +* +* @return The status of the operation. +* @retval 0 if WAN service stopped successfully. +* @retval -1 if any operation failed. +* +*/ +int wan_stop(struct serv_wan *sw); + +/** +* @brief Restart WAN service. +* +* This function restarts the WAN service by stopping and then starting it. +* +* @param[in] sw - Pointer to the serv_wan structure. +* +* @return The status of the start operation. +* @retval 0 if WAN service restarted successfully. +* @retval -1 if start operation failed. +* +*/ +int wan_restart(struct serv_wan *sw); + +/** +* @brief Start WAN DHCP service. +* +* This function starts the DHCP-based WAN service. +* +* @param[in] sw - Pointer to the serv_wan structure. +* +* @return The status of the operation. +* @retval 0 if DHCP service started successfully. +* @retval -1 if any operation failed. +* +*/ +int wan_dhcp_start(struct serv_wan *sw); + +/** +* @brief Set WAN address and configure routing. +* +* This function sets the WAN IP address and configures routing tables +* after DHCP or static configuration is complete. +* +* @param[in] sw - Pointer to the serv_wan structure. +* +* @return The status of the operation. +* @retval 0 if address was set successfully. +* @retval -1 if any operation failed. +* +*/ +int wan_addr_set(struct serv_wan *sw); + +/** +* @brief Restart WAN DHCP service. +* +* This function restarts the DHCP-based WAN service by stopping and starting it. +* +* @param[in] sw - Pointer to the serv_wan structure. +* +* @return The status of the start operation. +* @retval 0 if DHCP service restarted successfully. +* @retval -1 if start operation failed. +* +*/ +int wan_dhcp_restart(struct serv_wan *sw); +FILE* logfptr; } \ No newline at end of file diff --git a/source/ulog/ulog.h b/source/ulog/ulog.h index bd7ffafd..f44ca6ca 100644 --- a/source/ulog/ulog.h +++ b/source/ulog/ulog.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -54,7 +54,7 @@ typedef struct _sys_log_info{ pid_t pid; // process ID int gPrior; // global log priority int prior; // log priority - unsigned int enable; // logging enabled + unsigned int enable; // logging enabled FILE* stream; // stream of log file }_sys_Log_Info; @@ -68,13 +68,125 @@ typedef struct _sys_log_info{ #define ulog_LOG_Info(format, ...) ulog_sys(LOG_INFO, __FILE__, __LINE__, format, ##__VA_ARGS__) #define ulog_LOG_Dbg(format, ...) ulog_sys(LOG_DEBUG, __FILE__, __LINE__, format, ##__VA_ARGS__) +/** + * @brief Get the global log priority level. + * + * Retrieves the current global logging priority mask by querying the system's + * log mask and finding the highest enabled priority level. + * + * @return The current global log priority level. + * @retval LOG_EMERG to LOG_DEBUG - Valid priority level + * @retval -1 - No valid priority found in mask + * + */ int ulog_GetGlobalPrior(void); + +/** + * @brief Set the global log priority level. + * + * Configures the global logging priority mask using setlogmask() to filter messages + * at or below the specified priority level. + * + * @param[in] prior - Log priority level to set + * \n Valid range: LOG_EMERG (0) to LOG_DEBUG (7) + * + * @return void. + * + */ void ulog_SetGlobalPrior(int prior); + +/** + * @brief Get the current process log priority level. + * + * Retrieves the logging priority level stored in the sys_Log_Info structure + * for the current process. + * + * @return The current process log priority level. + * @retval LOG_EMERG to LOG_DEBUG - Current priority level from sys_Log_Info.prior. + * + */ int ulog_GetPrior(void); + +/** + * @brief Set the current process log priority level. + * + * Configures the logging priority level for the current process by updating + * the sys_Log_Info.prior field. Only accepts valid syslog priority values. + * + * @param[in] prior - Log priority level to set + * \n Valid range: LOG_EMERG (0) to LOG_DEBUG (7) + * @return void. + * + */ void ulog_SetPrior(int prior); + +/** + * @brief Get the current process name and ID. + * + * Retrieves the process name by reading /proc/[pid]/stat and obtains the process ID + * via getpid(). Extracts the process name from the stat file's second field. + * + * @param[in] size - Maximum size of the name buffer + * \n Must be greater than 0 + * @param[out] name - Buffer to store the extracted process name + * \n Will be null-terminated + * \n Receives name from /proc/[pid]/stat with trailing ')' removed + * @param[out] pid - Pointer to store the process ID + * \n Receives value from getpid() + * + * @return The status of the operation. + * @retval 0 - Success, name and pid retrieved + * @retval -1 - Invalid parameters or failed to read /proc/[pid]/stat + * + */ int ulog_GetProcId(size_t size, char *name, pid_t *pid); + +/** + * @brief Get the logging enabled state. + * + * Retrieves the current logging enable flag from the sys_Log_Info structure. + * + * @return The current logging enabled state. + * @retval 1 - Logging is enabled + * @retval 0 - Logging is disabled + * + */ unsigned int ulog_GetEnable(void); + +/** + * @brief Set the logging enabled state. + * + * Configures whether logging is enabled for the current process by updating + * the sys_Log_Info.enable field. + * + * @param[in] enable - Logging enable flag + * \n 1 = Enable logging + * \n 0 = Disable logging + * + * @return void. + * + */ void ulog_SetEnable(unsigned int enable); + +/** + * @brief Log a system message with file location and timestamp. + * + * Logs a formatted message to syslog with the specified priority, including timestamp, + * source file name, and line number. Formats the message with current date/time down to + * microseconds. + * + * @param[in] prior - Syslog priority level + * \n Valid range: LOG_EMERG (0) to LOG_DEBUG (7) + * @param[in] fileName - Source file name where log is invoked + * \n Typically __FILE__ macro + * @param[in] line - Line number in source file + * \n Typically __LINE__ macro + * @param[in] format - Printf-style format string for the log message + * @param[in] ... - Variable arguments corresponding to format specifiers + * + * @return void. + * + */ void ulog_sys(int prior, const char* fileName, int line, const char* format, ...); typedef enum { @@ -97,7 +209,7 @@ typedef enum { /* SYSTEM */ UL_SYSEVENT, UL_SYSCFG, - UL_UTCTX, + UL_UTCTX, /* LAN */ UL_DHCPSERVER, /* WAN */ @@ -121,136 +233,166 @@ typedef enum { } USUBCOMP; -/* - * Procedure : ulog_init - * Purpose : Per process initialization of logging infrastruture - * Parameters : None - * Return Values : None - * Notes : - * Opens connect to system logget and sets up a prefix string - * Current prefix string is "UTOPIA: " +/** + * @brief Initialize the Utopia logging infrastructure for the current process. + * + * Per-process initialization of logging infrastructure. Opens connection to system logger + * (syslog) using the ULOG_IDENT ("UTOPIA") prefix and LOG_LOCAL7 facility with LOG_NDELAY option. + * Must be called before using other ulog functions. + * + * @return void. */ void ulog_init(); -/* - * Procedure : ulog - * Purpose : Log a general message to system logger - * Parameters : - * UCOMP - component id - * USUBCOMP - subcomponent id - * mesg - message string - * Return Values : None - * Notes : - * uses syslog LOCAL7.NOTICE facility +/** + * @brief Log a general message to system logger with component categorization. + * + * Logs a simple string message at LOG_NOTICE priority level to syslog, prefixed with + * component.subcomponent identifiers for categorization and filtering. + * + * @param[in] comp - Component identifier from UCOMP enumeration + * @param[in] sub - Subcomponent identifier from USUBCOMP enumeration + * @param[in] mesg - Message string to log + * + * @return void. + * + * @note uses syslog LOCAL7.NOTICE facility */ void ulog (UCOMP comp, USUBCOMP sub, const char *mesg); -/* - * Procedure : ulogf - * Purpose : Log a message to system logger with variable arg - * Parameters : - * UCOMP - component id - * USUBCOMP - subcomponent id - * fmt - format of message string - * ... - variable args format for message string - * Return Values : None - * Notes : - * uses syslog LOCAL7.NOTICE facility +/** + * @brief Log a formatted message to system logger with variable arguments. + * + * Logs a printf-style formatted message at LOG_NOTICE priority level to syslog, + * prefixed with component.subcomponent identifiers. Supports variable argument lists. + * + * @param[in] comp - Component identifier from UCOMP enumeration + * @param[in] sub - Subcomponent identifier from USUBCOMP enumeration + * @param[in] fmt - Printf-style format string for the message + * @param[in] ... - Variable arguments corresponding to format specifiers + * + * @return void + * + * @note uses syslog LOCAL7.NOTICE facility */ void ulogf (UCOMP comp, USUBCOMP sub, const char *fmt, ...); -/* - * Procedure : ulog_debug - * Purpose : Log a debug message to system logger - * Parameters : - * UCOMP - component id - * USUBCOMP - subcomponent id - * mesg - message string - * Return Values : None - * Notes : - * uses syslog LOCAL7.DEBUG facility +/** + * @brief Log a debug message to system logger. + * + * Logs a debug-level string message at LOG_DEBUG priority to syslog, prefixed with + * component.subcomponent identifiers. Intended for detailed debugging information. + * + * @param[in] comp - Component identifier from UCOMP enumeration + * @param[in] sub - Subcomponent identifier from USUBCOMP enumeration + * @param[in] mesg - Debug message string to log + * + * @return void + * + * @note uses syslog LOCAL7.DEBUG facility */ void ulog_debug (UCOMP comp, USUBCOMP sub, const char *mesg); -/* - * Procedure : ulog_debugf - * Purpose : Log debug message to system logger with variable arg - * Parameters : - * UCOMP - component id - * USUBCOMP - subcomponent id - * fmt - format of message string - * ... - variable args format for message string - * Return Values : None - * Notes : - * uses syslog LOCAL7.DEBUG facility +/** + * @brief Log a formatted debug message to system logger with variable arguments. + * + * Logs a printf-style formatted debug message at LOG_DEBUG priority to syslog, + * prefixed with component.subcomponent identifiers. Supports variable argument lists. + * + * @param[in] comp - Component identifier from UCOMP enumeration + * @param[in] sub - Subcomponent identifier from USUBCOMP enumeration + * @param[in] fmt - Printf-style format string for the debug message + * @param[in] ... - Variable arguments corresponding to format specifiers + * + * @return void + * + * @note uses syslog LOCAL7.DEBUG facility */ void ulog_debugf (UCOMP comp, USUBCOMP sub, const char *fmt, ...); -/* - * Procedure : ulog_error - * Purpose : Log an error message to system logger - * Parameters : - * UCOMP - component id - * USUBCOMP - subcomponent id - * mesg - message string - * Return Values : None - * Notes : - * uses syslog LOCAL7.ERROR facility +/** + * @brief Log an error message to system logger. + * + * Logs an error-level string message at LOG_ERR priority to syslog, prefixed with + * component.subcomponent identifiers. Used for reporting error conditions. + * + * @param[in] comp - Component identifier from UCOMP enumeration + * @param[in] sub - Subcomponent identifier from USUBCOMP enumeration + * @param[in] mesg - Error message string to log + * + * @return void + * + * @note uses syslog LOCAL7.ERROR facility */ void ulog_error (UCOMP comp, USUBCOMP sub, const char *mesg); -/* - * Procedure : ulog_errorf - * Purpose : Log error message to system logger with variable arg - * Parameters : - * UCOMP - component id - * USUBCOMP - subcomponent id - * mesg - message string - * Return Values : None - * Notes : - * uses syslog LOCAL7.ERR facility +/** + * @brief Log a formatted error message to system logger with variable arguments. + * + * Logs a printf-style formatted error message at LOG_ERR priority to syslog, + * prefixed with component.subcomponent identifiers. Supports variable argument lists. + * + * @param[in] comp - Component identifier from UCOMP enumeration + * @param[in] sub - Subcomponent identifier from USUBCOMP enumeration + * @param[in] fmt - Printf-style format string for the error message + * @param[in] ... - Variable arguments corresponding to format specifiers + * + * @return void + * + * @note uses syslog LOCAL7.ERROR facility */ void ulog_errorf (UCOMP comp, USUBCOMP sub, const char *fmt, ...); -/* - * Procedure : ulog_get_mesgs - * Purpose : Retrieve mesgs for given component.subcomponent - * Parameters : - * UCOMP - component id - * USUBCOMP - subcomponent id - * mesgbuf - message strings output buffer - * size - size of above buffer - * Return Values : None - * Notes : - * mesgbuf will be truncated before mesgs are stored, - * and upto allowed size +/** + * @brief Retrieve logged messages for a given component.subcomponent. + * + * Retrieves previously logged messages from the system log that match the specified + * component and subcomponent identifiers. The messages are stored in the provided buffer. + * + * @param[in] comp - Component identifier from UCOMP enumeration + * @param[in] sub - Subcomponent identifier from USUBCOMP enumeration + * @param[out] mesgbuf - Buffer to store retrieved message strings + * \n Will be truncated and null-terminated + * @param[in] size - Size of the mesgbuf buffer in bytes + * + * @return void + * + * @note mesgbuf will be truncated before mesgs are stored, and upto allowed size. */ void ulog_get_mesgs (UCOMP comp, USUBCOMP sub, char *mesgbuf, unsigned int size); #if 0 -/* - * Procedure : ulog_runcmd - * Purpose : Log and run command string - * Parameters : - * UCOMP - component id - * USUBCOMP - subcomponent id - * cmd - command string - * Return Values : None - * Notes : - * uses syslog LOCAL7.NOTICE facility +/** + * @brief Log and execute a command string. + * + * Logs the command string at LOG_NOTICE priority to syslog with component.subcomponent + * prefix, then executes the command using system(). + * + * @param[in] comp - Component identifier from UCOMP enumeration + * @param[in] sub - Subcomponent identifier from USUBCOMP enumeration + * @param[in] cmd - Command string to log and execute + * + * @return void. + * + * @note uses syslog LOCAL7.NOTICE facility */ void ulog_runcmd (UCOMP comp, USUBCOMP sub, const char *cmd); -/* - * Procedure : ulog_runcmdf - * Purpose : Log and run command string with variable arg - * Parameters : - * UCOMP - component id - * USUBCOMP - subcomponent id - * mesg - message string - * Return Values : None - * Notes : - * uses syslog LOCAL7.NOTICE facility +/** + * @brief Log and execute a formatted command string with variable arguments. + * + * Logs a printf-style formatted command at LOG_NOTICE priority to syslog with + * component.subcomponent prefix, then executes the formatted command using system(). + * + * @param[in] comp - Component identifier from UCOMP enumeration + * @param[in] sub - Subcomponent identifier from USUBCOMP enumeration + * @param[in] fmt - Printf-style format string for the command + * @param[in] ... - Variable arguments corresponding to format specifiers + * + * @return The status of the command execution. + * @retval Command exit status - Return value from system() call + * + * @note uses syslog LOCAL7.NOTICE facility */ int ulog_runcmdf (UCOMP comp, USUBCOMP sub, const char *fmt, ...); #endif diff --git a/source/utapi/lib/DM_TR181.h b/source/utapi/lib/DM_TR181.h index af9e1664..8e5904e8 100644 --- a/source/utapi/lib/DM_TR181.h +++ b/source/utapi/lib/DM_TR181.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -36,7 +36,7 @@ /* * DM_TR181_h - TR-181 data model structures - */ + */ #include #include @@ -93,7 +93,7 @@ typedef struct param_node_{ typedef struct _Obj_Device_MoCA_{ - int InterfaceNumberOfEntries; + int InterfaceNumberOfEntries; }Obj_Device_MoCA; typedef struct _Obj_Device_MoCA_Interface_i_static{ @@ -136,8 +136,8 @@ typedef struct _Obj_Device_MoCA_Interface_i_dyn{ typedef struct _Obj_Device_MoCA_Interface_i_cfg{ unsigned long InstanceNumber; char Alias[UTOPIA_TR181_PARAM_SIZE]; - - bool_t Enable; + + bool_t Enable; bool_t PreferredNC; bool_t PrivacyEnabledSetting; unsigned char FreqCurrentMaskSetting[HEX_SZ]; @@ -203,7 +203,7 @@ typedef struct _Obj_Device_MoCA_Interface_i_AssociatedDevice_i_{ bool_t QAM256Capable; unsigned long PacketAggregationCapability; unsigned long RxSNR; - bool_t Active; + bool_t Active; }Obj_Device_MoCA_Interface_i_AssociatedDevice_i; @@ -224,22 +224,265 @@ typedef struct _Obj_Device_DNS_Relay_{ int Type; }Obj_Device_DNS_Relay; +/** + * @brief Get TR-181 Device.MoCA.Interface.{i}. static parameters. + * + * Retrieves static (read-only) parameters for a MoCA interface by parsing mocacfg output. + * Populates the Obj_Device_MoCA_Interface_i_static structure with interface properties. + * + * @param[out] deviceMocaIntfStatic - Pointer to structure to receive static MoCA interface parameters + * + * @return The status of the operation. + * @retval SUCCESS - Parameters retrieved successfully + * @retval ERR_INVALID_ARGS - Input parameter is NULL + * @retval ERR_GENERAL - General error during file parsing + * + */ int Utopia_Get_TR181_Device_MoCA_Interface_i_Static(Obj_Device_MoCA_Interface_i_static *deviceMocaIntfStatic); + +/** + * @brief Get TR-181 Device.MoCA.Interface.{i}. dynamic parameters. + * + * Retrieves dynamic (runtime) parameters for a MoCA interface by parsing mocacfg output. + * Populates the Obj_Device_MoCA_Interface_i_dyn structure with current interface state. + * + * @param[out] deviceMocaIntfDyn - Pointer to structure to receive dynamic MoCA interface parameters + * + * @return The status of the operation. + * @retval SUCCESS - Parameters retrieved successfully + * @retval ERR_INVALID_ARGS - Input parameter is NULL + * @retval ERR_GENERAL - General error during file parsing + * + */ int Utopia_Get_TR181_Device_MoCA_Interface_i_Dyn(Obj_Device_MoCA_Interface_i_dyn *deviceMocaIntfDyn); +/** + * @brief Get MoCA interface static parameters (wrapper function). + * + * Wrapper function that executes mocacfg commands to generate configuration files, + * then calls Utopia_Get_TR181_Device_MoCA_Interface_i_Static() to retrieve static parameters. + * + * @param[in,out] str_handle - Pointer to Obj_Device_MoCA_Interface_i_static structure + * \n Cast from void* for generic interface + * + * @return The status of the operation. + * @retval UT_SUCCESS - Static parameters retrieved successfully + * @retval ERR_INVALID_ARGS - Input parameter is NULL + * @retval ERR_ITEM_NOT_FOUND - Failed to retrieve MoCA interface data + * + */ int Utopia_GetMocaIntf_Static(void *str_handle); + +/** + * @brief Get MoCA interface dynamic parameters (wrapper function). + * + * Wrapper function that executes mocacfg commands to generate configuration files, + * then calls Utopia_Get_TR181_Device_MoCA_Interface_i_Dyn() to retrieve dynamic parameters. + * + * @param[in,out] str_handle - Pointer to Obj_Device_MoCA_Interface_i_dyn structure + * \n Cast from void* for generic interface + * + * @return The status of the operation. + * @retval UT_SUCCESS - Dynamic parameters retrieved successfully + * @retval ERR_INVALID_ARGS - Input parameter is NULL + * @retval ERR_ITEM_NOT_FOUND - Failed to retrieve MoCA interface data + * + */ int Utopia_GetMocaIntf_Dyn(void *str_handle); + +/** + * @brief Get MoCA interface configuration parameters. + * + * Retrieves configurable MoCA interface parameters from Utopia context (syscfg). + * Populates the Obj_Device_MoCA_Interface_i_cfg structure with current settings. + * + * @param[in] pCtx - Pointer to Utopia context + * @param[in,out] str_handle - Pointer to Obj_Device_MoCA_Interface_i_cfg structure + * \n Cast from void* for generic interface + * + * @return The status of the operation. + * @retval UT_SUCCESS - Configuration parameters retrieved successfully + * @retval ERR_INVALID_ARGS - pCtx or str_handle is NULL + * + */ int Utopia_GetMocaIntf_Cfg(UtopiaContext *pCtx, void *str_handle); + +/** + * @brief Set MoCA interface configuration parameters. + * + * Applies MoCA interface configuration by updating Utopia context (syscfg) and + * executing mocacfg commands to configure the MoCA interface. + * + * @param[in] pCtx - Pointer to Utopia context + * @param[in] str_handle - Pointer to Obj_Device_MoCA_Interface_i_cfg structure with new settings + * \n Cast from void* for generic interface + * + * @return The status of the operation. + * @retval UT_SUCCESS - Configuration applied successfully + * @retval ERR_INVALID_ARGS - pCtx or str_handle is NULL + * + */ int Utopia_SetMocaIntf_Cfg(UtopiaContext *pCtx, void *str_handle); + +/** + * @brief Count MoCA associated device entries. + * + * Counts the number of devices currently associated with the MoCA network by parsing + * the associated devices file. + * + * @param[out] devCount - Pointer to integer to receive device count + * + * @return The status of the operation. + * @retval SUCCESS - Device count retrieved successfully + * @retval ERR_GENERAL - General error. + * + */ int Utopia_Count_AssociateDeviceEntry(int *devCount); + +/** + * @brief Get MoCA associated device information. + * + * Retrieves information about a specific associated device on the MoCA network. + * Populates the Obj_Device_MoCA_Interface_i_AssociatedDevice_i structure. + * + * @param[out] mocaIntfAssociatedevice - Pointer to structure to receive associated device information + * @param[in] count - Index of the associated device to retrieve (0-based) + * + * @return The status of the operation. + * @retval SUCCESS - Device information retrieved successfully + * @retval ERR_INVALID_ARGS - mocaIntfAssociatedevice parameter is NULL + * @retval ERR_GENERAL - General error during file parsing + * + */ int Utopia_Get_TR181_Device_MoCA_Interface_i_AssociateDevice(Obj_Device_MoCA_Interface_i_AssociatedDevice_i *mocaIntfAssociatedevice, int count); +/** + * @brief Get DNS relay forwarding configuration. + * + * Retrieves DNS relay forwarding entry configuration from Utopia context for the specified index. + * Populates the Obj_Device_DNS_Relay structure with Enable, DNSServer, and Interface parameters. + * + * @param[in] pCtx - Pointer to Utopia context + * @param[in] index - Index of the DNS forwarding entry to retrieve + * @param[in,out] str_handle - Pointer to Obj_Device_DNS_Relay structure + * \n Cast from void* for generic interface + * + * @return The status of the operation. + * @retval UT_SUCCESS - Configuration retrieved successfully + * @retval ERR_INVALID_ARGS - str_handle parameter is NULL + * + */ int Utopia_Get_DeviceDnsRelayForwarding(UtopiaContext *pCtx, int index, void *str_handle); + +/** + * @brief Set DNS relay forwarding configuration. + * + * Stores DNS relay forwarding entry configuration to Utopia context for the specified index. + * Updates Enable, DNSServer, and Interface parameters from Obj_Device_DNS_Relay structure. + * + * @param[in] pCtx - Pointer to Utopia context + * @param[in] index - Index of the DNS forwarding entry to configure + * @param[in] str_handle - Pointer to Obj_Device_DNS_Relay structure with new settings + * \n Cast from void* for generic interface + * + * @return The status of the operation. + * @retval UT_SUCCESS - Configuration stored successfully + * @retval ERR_INVALID_ARGS - pCtx or str_handle parameter is NULL + * + */ int Utopia_Set_DeviceDnsRelayForwarding(UtopiaContext *pCtx, int index, void *str_handle); +/** + * @brief Parse configuration file into parameter list. + * + * Parses a configuration file line by line, extracting parameter name-value pairs separated by + * colons. Builds a linked list of param_node structures containing the parsed parameters. + * + * @param[in] file_name - Path to configuration file to parse + * @param[out] head - Pointer to head pointer of parameter list + * \n Will be populated with linked list of param_node structures + * + * @return The status of the operation. + * @retval SUCCESS - File parsed successfully + * @retval ERR_INVALID_PARAM - file_name or head parameter is NULL + * @retval ERR_FILE_OPEN_FAIL - Failed to open file + * @retval ERR_FILE_CLOSE_FAIL - Failed to close file + * @retval ERR_INSUFFICIENT_MEM - Memory allocation failed + * + */ int file_parse(char* file_name, param_node **head); + +/** + * @brief Free parameter list. + * + * Frees all nodes in a parameter linked list and sets head pointer to NULL. + * + * @param[in,out] head - Head pointer of parameter list to free + * \n All nodes in list will be freed + * + * @return None. + * + */ void free_paramList(param_node *head); + +/** + * @brief Convert MAC address string to byte array. + * + * Parses a MAC address string in various formats (with colons, dashes, or underscores) + * and converts it to a 6-byte array representation. + * + * @param[in] macAddress - MAC address string to parse + * \n Supports formats: "AABBCCDDEEFF", "AA:BB:CC:DD:EE:FF", + * "AA-BB-CC-DD-EE-FF", "AA_BB_CC_DD_EE_FF" + * @param[in] len - If non-zero, validates MAC length is exactly MAC_SZ (6) bytes + * \n If zero, allows MAC length up to MAC_SZ bytes + * @param[out] mac - Pointer to 6-byte array to receive MAC address + * \n Buffer must be at least MAC_SZ (6) bytes + * + * @return The status of the operation. + * @retval SUCCESS - MAC address converted successfully + * @retval ERR_INVALID_PARAM - macAddress is NULL, length < MIN_MAC_LEN (12), invalid hex format, or incorrect byte count + * + */ int getMac(char * macAddress, int len, unsigned char * mac); + +/** + * @brief Convert hexadecimal string to byte array. + * + * Parses a hexadecimal string (with optional "0x" prefix) and converts it to a byte array. + * Pads with leading zeros if input string is shorter than expected length. + * + * @param[in] hex_val - Hexadecimal string to parse + * \n Supports format: "0x1234ABCD" or "1234ABCD" + * \n Separators (colon, dash, underscore) supported between bytes + * @param[out] hexVal - Pointer to byte array to receive hex value + * \n Buffer must be at least hexLen bytes + * @param[in] hexLen - Expected length of output in bytes + * \n For hexLen=8, input padded to MAX_HEX_LEN (16) hex digits + * + * @return The status of the operation. + * @retval SUCCESS - Hex string converted successfully + * @retval ERR_INVALID_PARAM - hex_val is NULL or converted length doesn't match hexLen + * + */ int getHex(char *hex_val, unsigned char *hexVal, int hexLen); + +/** + * @brief Convert hexadecimal string to byte array (generic version). + * + * Parses a hexadecimal string and converts it to a byte array without special formatting. + * Similar to getHex() but without automatic padding for hexLen=8. + * + * @param[in] hex_val - Hexadecimal string to parse + * \n Format: hex digits with optional separators (colon, dash, underscore) + * @param[out] hexVal - Pointer to byte array to receive hex value + * \n Buffer must be at least hexLen bytes + * @param[in] hexLen - Expected length of output in bytes + * + * @return The status of the operation. + * @retval SUCCESS - Hex string converted successfully + * @retval ERR_INVALID_PARAM - hex_val is NULL or converted length doesn't match hexLen + * + */ int getHexGeneric(char *hex_val, unsigned char *hexVal, int hexLen); diff --git a/source/utapi/lib/utapi.h b/source/utapi/lib/utapi.h index 0b960dce..06828152 100644 --- a/source/utapi/lib/utapi.h +++ b/source/utapi/lib/utapi.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -65,7 +65,7 @@ typedef int token_t; /* * General */ - + typedef char* String; typedef int boolean_t; @@ -81,8 +81,8 @@ typedef int boolean_t; #define IPHOSTNAME_SZ 128 // hostname foo.domain.com or IP address #define PORT_SZ 6 // port number 0 - 65535 #define URL_SZ 512 // http://foo.domain.com/blahblah -#define IFNAME_SZ 16 // size of interface names like br0, vlan2, eth3 -#define TOKEN_SZ 128 // generic token +#define IFNAME_SZ 16 // size of interface names like br0, vlan2, eth3 +#define TOKEN_SZ 128 // generic token #define USERNAME_SZ 64 #define PASSWORD_SZ 64 #define WAN_SERVICE_NAME_SZ 64 @@ -129,7 +129,7 @@ typedef int boolean_t; typedef struct { unsigned int magic; unsigned int len; - unsigned int version; + unsigned int version; unsigned int crc32; } config_hdr_t; @@ -177,7 +177,7 @@ typedef enum { typedef enum { INTERFACE_LAN, INTERFACE_WAN, -} interface_t; +} interface_t; /* @@ -243,7 +243,7 @@ typedef struct wanInfo { boolean_t auto_mtu; // true - automatically picked, false - set it to size specified int mtu_size; }__attribute__ ((__packed__)) wanInfo_t; - + /* * Router/Bridge settings */ @@ -291,8 +291,8 @@ typedef enum ddnsProvider { DDNS_TZO, DDNS_EASYDNS, DDNS_EASYDNS_PARTNER, - DDNS_GNUDIP, - DDNS_JUSTLINUX, + DDNS_GNUDIP, + DDNS_JUSTLINUX, DDNS_DYNS, DDNS_HN, DDNS_ZONEEDIT, @@ -336,7 +336,7 @@ typedef struct routeStatic { char dest_lan_ip[IPADDR_SZ]; char netmask[IPADDR_SZ]; char gateway[IPADDR_SZ]; - interface_t dest_intf; + interface_t dest_intf; } routeStatic_t; typedef struct routeEntry { @@ -360,13 +360,13 @@ typedef enum protocol { typedef struct portFwdSingle { char name[NAME_SZ]; boolean_t enabled; - boolean_t prevRuleEnabledState; + boolean_t prevRuleEnabledState; int rule_id; protocol_t protocol; int external_port; int internal_port; - char dest_ip[IPADDR_SZ]; - char dest_ipv6[64]; + char dest_ip[IPADDR_SZ]; + char dest_ipv6[64]; } portFwdSingle_t; typedef struct portMapDyn { @@ -384,22 +384,22 @@ typedef struct portMapDyn { typedef struct portFwdRange { char name[NAME_SZ]; boolean_t enabled; - boolean_t prevRuleEnabledState; + boolean_t prevRuleEnabledState; int rule_id; protocol_t protocol; int start_port; int end_port; int internal_port; int internal_port_range_size; - char dest_ip[IPADDR_SZ]; - char dest_ipv6[64]; - char public_ip[IPADDR_SZ]; + char dest_ip[IPADDR_SZ]; + char dest_ipv6[64]; + char public_ip[IPADDR_SZ]; } portFwdRange_t; typedef struct portRangeTrig { char name[TOKEN_SZ]; boolean_t enabled; - boolean_t prevRuleEnabledState; + boolean_t prevRuleEnabledState; int rule_id; protocol_t trigger_proto; protocol_t forward_proto; @@ -561,10 +561,75 @@ typedef struct qosPolicy { } qosPolicy_t; */ +/** +* @brief Get the list of predefined QoS (Quality of Service) policies. +* +* @param[out] out_count - Pointer to an integer where the count of QoS policies will be returned. +* @param[out] out_qoslist - Pointer to a qosDefinedPolicy_t const pointer where the list of QoS policies will be returned. +* \n Policies are read from /etc/qos_classification_rules file. +* \n Maximum policies: 256. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_FILE_NOT_FOUND if the QoS classification rules file cannot be opened. +* +*/ int Utopia_GetQoSDefinedPolicyList (int *out_count, qosDefinedPolicy_t const **out_qoslist); + +/** +* @brief Set the QoS (Quality of Service) settings. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] qos - Pointer to a qosInfo_t structure containing the QoS settings to be set. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx, qos is NULL, or if enable is TRUE with policy count > 0 but policy list is NULL. +* +*/ int Utopia_SetQoSSettings (UtopiaContext *ctx, qosInfo_t *qos); + +/** +* @brief Get the QoS (Quality of Service) settings. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] qos - Pointer to a qosInfo_t structure where the QoS settings will be returned. +* \n Caller must free policy_list after use. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or qos is NULL. +* @retval ERR_INSUFFICIENT_MEM if memory allocation fails. +* +*/ int Utopia_GetQoSSettings (UtopiaContext *ctx, qosInfo_t *qos); + +/** +* @brief Get comments/description for a LAN host identified by MAC address. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] pMac - Pointer to the MAC address buffer. +* @param[out] pComments - Pointer to the buffer where comments will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx, pMac, or pComments is NULL. +* +*/ int Utopia_get_lan_host_comments(UtopiaContext *ctx, unsigned char *pMac, unsigned char *pComments); + +/** +* @brief Set comments/description for a LAN host identified by MAC address. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] pMac - Pointer to the MAC address buffer. +* @param[in] pComments - Pointer to the comments buffer to be set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx, pMac, or pComments is NULL. +* +*/ int Utopia_set_lan_host_comments(UtopiaContext *ctx, unsigned char *pMac, unsigned char *pComments); /* @@ -679,7 +744,7 @@ typedef struct { typedef enum { LAN_INTERFACE_WIRED, LAN_INTERFACE_WIFI, -} lan_interface_t; +} lan_interface_t; /* * LAN setting @@ -717,16 +782,16 @@ typedef struct dhcpServerInfo { char StaticNameServer1[IPHOSTNAME_SZ]; char StaticNameServer2[IPHOSTNAME_SZ]; char StaticNameServer3[IPHOSTNAME_SZ]; - char WINSServer[IPHOSTNAME_SZ]; + char WINSServer[IPHOSTNAME_SZ]; } dhcpServerInfo_t; typedef struct dmz { boolean_t enabled; char source_ip_start[IPADDR_SZ]; // empty string means "any ip address" - char source_ip_end[IPADDR_SZ]; + char source_ip_end[IPADDR_SZ]; //int dest_ip; // last octet char dest_ip[IPADDR_SZ]; // full ip - char dest_mac[MACADDR_SZ]; + char dest_mac[MACADDR_SZ]; char dest_ipv6[64]; } dmz_t; @@ -739,31 +804,208 @@ typedef struct dmz { * Device Settings */ +/** +* @brief Get device settings including hostname, language, and timezone. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] device - Pointer to a deviceSetting_t structure where the device settings will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or device is NULL. +* +*/ int Utopia_GetDeviceSettings (UtopiaContext *ctx, deviceSetting_t *device); + +/** +* @brief Set device settings including hostname, language, and timezone. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] device - Pointer to a deviceSetting_t structure containing the device settings to be set. +* \n Timezone is determined by matching GMT offset and DST settings with internal timezone list. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or device is NULL. +* +*/ int Utopia_SetDeviceSettings (UtopiaContext *ctx, deviceSetting_t *device); /* * LAN Settings */ +/** +* @brief Get LAN (Local Area Network) settings. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] lan - Pointer to a lanSetting_t structure where the LAN settings will be returned. +* \n Domain is retrieved from sysevent or syscfg. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or lan is NULL. +* +*/ int Utopia_GetLanSettings (UtopiaContext *ctx, lanSetting_t *lan); + +/** +* @brief Set LAN (Local Area Network) settings. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] lan - Pointer to a lanSetting_t structure containing the LAN settings to be set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or lan is NULL. +* @retval ERR_INVALID_NETMASK if the netmask is invalid. +* +*/ int Utopia_SetLanSettings(UtopiaContext *ctx, lanSetting_t *lan); -int Utopia_SetDHCPServerSettings (UtopiaContext *ctx, dhcpServerInfo_t *dhcps); +/** +* @brief Set the DHCP server settings. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] dhcps - Pointer to a dhcpServerInfo_t structure containing the DHCP server settings to be set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or dhcps is NULL. +* +*/ +int Utopia_SetDHCPServerSettings (UtopiaContext *ctx, dhcpServerInfo_t *dhcps); + +/** +* @brief Get the DHCP server settings. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] dhcps - Pointer to a dhcpServerInfo_t structure where the DHCP server settings will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or out_dhcps is NULL. +* +*/ int Utopia_GetDHCPServerSettings (UtopiaContext *ctx, dhcpServerInfo_t *out_dhcps); +/** +* @brief Set DHCP server static host mappings. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] count - Number of static host entries to set. +* @param[in] dhcpMap - Pointer to an array of DHCPMap_t structures containing static host mappings. +* \n MAC address and IP address are validated before setting. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx is NULL. +* @retval ERR_INVALID_VALUE if MAC address or IP address is invalid. +* +*/ int Utopia_SetDHCPServerStaticHosts (UtopiaContext *ctx, int count, DHCPMap_t *dhcpMap); + +/** +* @brief Get DHCP server static host mappings. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] count - Pointer to an integer where the count of static hosts will be returned. +* @param[out] dhcpMap - Pointer to a DHCPMap_t pointer where the static host mappings will be returned. +* \n Format: "macaddr,last octet of host_ip,client_name" or None +* \n Caller must free dhcpMap after use. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx, count, or dhcpMap is NULL. +* @retval ERR_INSUFFICIENT_MEM if memory allocation fails. +* +*/ int Utopia_GetDHCPServerStaticHosts (UtopiaContext *ctx, int *count, DHCPMap_t **dhcpMap); + +/** +* @brief Get the count of DHCP server static host entries. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] count - Pointer to an integer where the count of static hosts will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_GetDHCPServerStaticHostsCount (UtopiaContext *ctx, int *count); + +/** +* @brief Remove all DHCP server static host entries. +* +* @param[in] ctx - Pointer to the Utopia context. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx is NULL. +* +*/ int Utopia_UnsetDHCPServerStaticHosts (UtopiaContext *ctx); +/** +* @brief Get ARP (Address Resolution Protocol) cache entries. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] count - Pointer to an integer where the count of ARP entries will be returned. +* @param[out] out_hosts - Pointer to an arpHost_t pointer where the ARP cache entries will be returned. +* \n Caller must free out_hosts after use. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_INSUFFICIENT_MEM if memory allocation fails. +* +*/ int Utopia_GetARPCacheEntries (UtopiaContext *ctx, int *count, arpHost_t **out_hosts); + +/** +* @brief Get the list of WLAN (WiFi) clients connected to the access point. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] count - Pointer to an integer where the count of WLAN clients will be returned. +* @param[out] out_maclist - Pointer to a char pointer where the MAC address list will be returned. +* \n MAC addresses are stored contiguously, each 18 bytes. +* \n Caller must free out_maclist after use. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_INSUFFICIENT_MEM if memory allocation fails. +* +*/ int Utopia_GetWLANClients (UtopiaContext *ctx, int *count, char **out_maclist); -// Used for status and display current DHCP leases +/** +* @brief Get the list of active DHCP leases and on the LAN. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] count - Pointer to an integer where the count of DHCP leases will be returned. +* @param[out] client_info - Pointer to a dhcpLANHost_t pointer where the lease information will be returned. +* \n Lease information is read from /tmp/dnsmasq.leases file. +* \n Caller must free client_info after use. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INSUFFICIENT_MEM if memory allocation fails. +* +*/ int Utopia_GetDHCPServerLANHosts (UtopiaContext *ctx, int *count, dhcpLANHost_t **client_info); + +/** +* @brief Delete a DHCP lease for a specific IP address. +* +* @param[in] ipaddr - Pointer to the IP address string of the lease to delete. +* \n Triggers dhcp_server-restart sysevent. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_SYSEVENT_CONN if unable to connect to sysevent daemon. +* +*/ int Utopia_DeleteDHCPServerLANHost (char *ipaddr); @@ -771,48 +1013,410 @@ int Utopia_DeleteDHCPServerLANHost (char *ipaddr); * WAN Settings */ +/** +* @brief Set WAN (Wide Area Network) settings. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] wan_info - Pointer to a wanInfo_t structure containing the WAN settings to be set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or wan_info is NULL. +* @retval ERR_INVALID_WAN_TYPE if the WAN protocol is invalid. +* +*/ int Utopia_SetWANSettings (UtopiaContext *ctx, wanInfo_t *wan_info); + +/** +* @brief Get WAN (Wide Area Network) settings. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] wan_info - Pointer to a wanInfo_t structure where the WAN settings will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or wan_info is NULL. +* @retval ERR_INVALID_WAN_TYPE if the WAN protocol is invalid. +* +*/ int Utopia_GetWANSettings (UtopiaContext *ctx, wanInfo_t *wan_info); #if !defined(DDNS_BROADBANDFORUM) +/** +* @brief Set DDNS (Dynamic DNS) service settings. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ddns - Pointer to a ddnsService_t structure containing the DDNS settings to be set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_DDNS_TYPE if the DDNS provider type is invalid. +* +*/ int Utopia_SetDDNSService (UtopiaContext *ctx, ddnsService_t *ddns); + +/** +* @brief Trigger an update of the DDNS service. +* +* @param[in] ctx - Pointer to the Utopia context. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_UpdateDDNSService (UtopiaContext *ctx); + +/** +* @brief Get DDNS (Dynamic DNS) service settings. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] ddns - Pointer to a ddnsService_t structure where the DDNS settings will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_GetDDNSService (UtopiaContext *ctx, ddnsService_t *ddns); + +/** +* @brief Get the current DDNS service status. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] ddnsStatus - Pointer to a ddnsStatus_t where the DDNS status will be returned. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_SYSEVENT_CONN if unable to connect to sysevent daemon. +* @retval ERR_INVALID_ARGS if ctx or ddnsStatus is NULL. +* +*/ int Utopia_GetDDNSServiceStatus (UtopiaContext *ctx, ddnsStatus_t *ddnsStatus); #endif +/** +* @brief Set MAC address cloning for the WAN interface. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] enable - Boolean flag to enable or disable MAC cloning. +* @param[in] macaddr - MAC address string to clone (18 bytes). +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_MAC if the provided MAC address is invalid. +* +*/ int Utopia_SetMACAddressClone (UtopiaContext *ctx, boolean_t enable, char macaddr[MACADDR_SZ]); + +/** +* @brief Get MAC address cloning settings for the WAN interface. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] enable - Pointer to a boolean_t where the MAC cloning enable status will be returned. +* @param[out] macaddr - Buffer where the cloned MAC address will be returned (18 bytes). +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx, enable, or macaddr is NULL. +* +*/ int Utopia_GetMACAddressClone (UtopiaContext *ctx, boolean_t *enable, char macaddr[MACADDR_SZ]); +/** +* @brief Release the current DHCP lease on the WAN interface. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_UTCTX_INIT if Utopia context initialization fails. +* @retval ERR_INVALID_WAN_TYPE if the WAN protocol is not DHCP. +* @retval ERR_SYSEVENT_CONN if unable to connect to sysevent daemon. +* +*/ int Utopia_WANDHCPClient_Release (void); + +/** +* @brief Renew the DHCP lease on the WAN interface. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_UTCTX_INIT if Utopia context initialization fails. +* @retval ERR_INVALID_WAN_TYPE if the WAN protocol is not DHCP. +* @retval ERR_SYSEVENT_CONN if unable to connect to sysevent daemon. +* +*/ int Utopia_WANDHCPClient_Renew (void); +/** +* @brief Terminate the WAN connection. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_SYSEVENT_CONN if unable to connect to sysevent daemon. +* +*/ int Utopia_WANConnectionTerminate (void); + +/** +* @brief Get WAN connection information. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] info - Pointer to a wanConnectionInfo_t structure where the connection information will be returned. +* \n Information source depends on WAN protocol (DHCP/PPP/STATIC). +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or info is NULL. +* @retval ERR_SYSEVENT_CONN if unable to connect to sysevent daemon. +* +*/ int Utopia_GetWANConnectionInfo (UtopiaContext *ctx, wanConnectionInfo_t *info); + +/** +* @brief Get WAN connection status. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] wan - Pointer to a wanConnectionStatus_t structure where the connection status will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or wan is NULL. +* @retval ERR_SYSEVENT_CONN if unable to connect to sysevent daemon. +* +*/ int Utopia_GetWANConnectionStatus (UtopiaContext *ctx, wanConnectionStatus_t *wan); + +/** +* @brief Get WAN traffic statistics. +* +* @param[out] wan - Pointer to a wanTrafficInfo_t structure where the traffic statistics will be returned. +* \n Statistics are read from /proc/net/dev. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if wan is NULL. +* @retval ERR_SYSEVENT_CONN if unable to connect to sysevent daemon. +* @retval ERR_FILE_READ_FAILED if /proc/net/dev cannot be opened. +* +*/ int Utopia_GetWANTrafficInfo (wanTrafficInfo_t *wan); /* * Router/Bridge settings */ +/** +* @brief Set bridge mode settings. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] bridge_info - Pointer to a bridgeInfo_t structure containing the bridge settings to be set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or bridge_info is NULL. +* @retval ERR_INVALID_BRIDGE_MODE if the bridge mode is invalid. +* +*/ int Utopia_SetBridgeSettings (UtopiaContext *ctx, bridgeInfo_t *bridge_info); + +/** +* @brief Get bridge mode settings. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] bridge_info - Pointer to a bridgeInfo_t structure where the bridge settings will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or bridge_info is NULL. +* @retval ERR_INVALID_BRIDGE_MODE if the bridge mode is invalid. +* +*/ int Utopia_GetBridgeSettings (UtopiaContext *ctx, bridgeInfo_t *bridge_info); + +/** +* @brief Get bridge connection information. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] bridge - Pointer to a bridgeConnectionInfo_t structure where the connection information will be returned. +* \n Returns zeroed struct if bridge mode is OFF. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or bridge is NULL. +* @retval ERR_SYSEVENT_CONN if unable to connect to sysevent daemon (DHCP mode). +* @retval ERR_INVALID_BRIDGE_MODE if the bridge mode is invalid. +* +*/ int Utopia_GetBridgeConnectionInfo (UtopiaContext *ctx, bridgeConnectionInfo_t *bridge); /* * Route Settings */ +/** +* @brief Set NAT (Network Address Translation) mode. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] enable - NAT mode to be set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_SetRouteNAT (UtopiaContext *ctx, napt_mode_t enable); + +/** +* @brief Get NAT (Network Address Translation) mode. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] enable - Pointer to a napt_mode_t where the NAT mode will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_GetRouteNAT (UtopiaContext *ctx, napt_mode_t *enable); +/** +* @brief Set RIP (Routing Information Protocol) settings. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] rip - Pointer to a routeRIP_t structure containing the RIP settings to be set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_SetRouteRIP (UtopiaContext *ctx, routeRIP_t *rip); //CID 67860: Big parameter passed by value + +/** +* @brief Get RIP (Routing Information Protocol) settings. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] rip - Pointer to a routeRIP_t structure where the RIP settings will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_GetRouteRIP (UtopiaContext *ctx, routeRIP_t *rip); +/** +* @brief Find a static route entry by name from an array of static routes. +* +* @param[in] count - The number of static route entries in the sroutes array. +* @param[in] sroutes - Pointer to an array of routeStatic_t structures containing the static routes to search. +* @param[in] route_name - Pointer to a null-terminated string containing the route name to search for. +* +* @return The index of the matched route (1-based), or -1 if not found. +* @retval 1 to count - Index of the matched static route entry (1-based). +* @retval -1 - Route not found. +* +*/ int Utopia_FindStaticRoute (int count, routeStatic_t *sroutes, const char *route_name); + +/** +* @brief Delete a static route entry by index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] index - The 1-based index of the static route to delete. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx is NULL. +* @retval ERR_ITEM_NOT_FOUND if index is out of range. +* +*/ int Utopia_DeleteStaticRoute (UtopiaContext *ctx, int index); + +/** +* @brief Delete a static route entry by its friendly name. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] route_name - Pointer to a null-terminated string containing the name of the route to delete. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or route_name is NULL. +* @retval ERR_ITEM_NOT_FOUND if no route with the specified name is found. +* +*/ int Utopia_DeleteStaticRouteName (UtopiaContext *ctx, const char *route_name); + +/** +* @brief Add a new static route entry to the system configuration. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] sroute - Pointer to a routeStatic_t structure containing the static route information to add. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or sroute is NULL. +* @retval SUCCESS if the route is successfully added and count incremented. +* +*/ int Utopia_AddStaticRoute (UtopiaContext *ctx, routeStatic_t *sroute); + +/** +* @brief Edit an existing static route entry at the specified index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] index - The 1-based index of the static route to modify. +* @param[in] sroute - Pointer to a routeStatic_t structure containing the updated static route information. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx is NULL, index is less than 1, sroute is NULL, or index exceeds the route count. +* @retval SUCCESS if the route is successfully updated. +* +*/ int Utopia_EditStaticRoute (UtopiaContext *ctx, int index, routeStatic_t *sroute); + +/** +* @brief Get the number of configured static routes. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] count - Pointer to an integer where the static route count will be returned. +* \n Initialized to 0 before retrieval. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or count is NULL. +* +*/ int Utopia_GetStaticRouteCount (UtopiaContext *ctx, int *count); + +/** +* @brief Get all configured static routes from the system configuration. +* +* This function allocates memory for the route array. Caller is responsible for freeing the memory. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] count - Pointer to an integer where the number of static routes will be returned. +* @param[out] out_sroute - Pointer to a routeStatic_t pointer where the allocated array of static routes will be returned. +* \n Caller must free this memory when done. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful (including when count is 0). +* @retval ERR_INVALID_ARGS if ctx, count, or out_sroute is NULL. +* @retval ERR_INSUFFICIENT_MEM if memory allocation fails. +* @retval SUCCESS if all routes are successfully retrieved. +* +*/ int Utopia_GetStaticRoutes (UtopiaContext *ctx, int *count, routeStatic_t **out_sroute); + +/** +* @brief Get the current active routing table from the system kernel. +* \n +* Retrieves the actual routing table by executing 'route -en' command and parsing the output. +* \n This function allocates memory for the route array. Caller is responsible for freeing the memory. +* +* @param[out] count - Pointer to an integer where the number of route entries will be returned. +* @param[out] out_sroute - Pointer to a routeStatic_t pointer where the allocated array of route entries will be returned. +* \n Caller must free this memory when done. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if count or out_sroute is NULL. +* @retval ERR_SYSEVENT_CONN if sysevent connection fails. +* @retval ERR_FILE_NOT_FOUND if the temporary route table file cannot be opened. +* @retval ERR_INSUFFICIENT_MEM if memory allocation fails. +* +*/ int Utopia_GetStaticRouteTable (int *count, routeStatic_t **out_sroute); /* @@ -823,69 +1427,829 @@ int Utopia_GetStaticRouteTable (int *count, routeStatic_t **out_sroute); * Port Mapping */ +/** +* @brief Check if a port trigger range conflicts with existing port trigger rules. +* +* Validates that the specified trigger port range does not overlap with existing port trigger configurations. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] new_rule_id - The rule ID of the new/edited rule (existing rules with this ID are skipped in validation). +* @param[in] new_start - The starting port number of the range to validate. +* @param[in] new_end - The ending port number of the range to validate. +* @param[in] new_protocol - The protocol type (TCP, UDP, BOTH_TCP_UDP). +* @param[in] is_trigger - Flag indicating if this is a trigger port check (1) or forwarding port check (0). +* +* @return Validation result. +* @retval TRUE if the port range is valid (no conflicts). +* @retval FALSE if the port range conflicts with an existing trigger rule. +* +*/ int Utopia_CheckPortTriggerRange(UtopiaContext *ctx, int new_rule_id, int new_start, int new_end, int new_protocol, int is_trigger); + +/** +* @brief Check if a port range conflicts with existing port forwarding and port trigger rules. +* +* Validates that the specified port range does not overlap with existing single port forwarding, +* port range forwarding, or port triggering forwarding port configurations. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] new_rule_id - The rule ID of the new/edited rule (existing rules with this ID are skipped in validation). +* @param[in] new_start - The starting port number of the range to validate. +* @param[in] new_end - The ending port number of the range to validate. +* @param[in] new_protocol - The protocol type (TCP, UDP, BOTH_TCP_UDP). +* @param[in] is_trigger - Flag indicating if this is a trigger port check (1) or forwarding port check (0). +* +* @return Validation result. +* @retval TRUE if the port range is valid (no conflicts). +* @retval FALSE if the port range conflicts with an existing rule. +* +*/ int Utopia_CheckPortRange(UtopiaContext *ctx, int new_rule_id, int new_start, int new_end, int new_protocol, int is_trigger); +/** +* @brief Set the complete list of single port forwarding rules, replacing all existing rules. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] count - The number of port forwarding rules in the fwdinfo array. +* @param[in] fwdinfo - Pointer to an array of portFwdSingle_t structures containing the port forwarding rules. +* \n If rule_id is 0, it will be auto-assigned based on array position for backward compatibility. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_VALUE if any rule_id is negative. +* @retval ERR_INVALID_IP if any destination IP address is invalid. +* +*/ int Utopia_SetPortForwarding (UtopiaContext *ctx, int count, portFwdSingle_t *fwdinfo); + +/** +* @brief Get all configured single port forwarding rules. +* \n +* This function allocates memory for the forwarding rules array. Caller is responsible for freeing the memory. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] count - Pointer to an integer where the number of port forwarding rules will be returned. +* @param[out] fwdinfo - Pointer to a portFwdSingle_t pointer where the allocated array of forwarding rules will be returned. +* \n Caller must free this memory when done. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful (including when count is 0). +* @retval ERR_INSUFFICIENT_MEM if memory allocation fails. +* +*/ int Utopia_GetPortForwarding (UtopiaContext *ctx, int *count, portFwdSingle_t **fwdinfo); + +/** +* @brief Get the number of configured single port forwarding rules. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] count - Pointer to an integer where the port forwarding rule count will be returned. +* \n Initialized to 0 before retrieval. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_GetPortForwardingCount (UtopiaContext *ctx, int *count); + +/** +* @brief Find a port forwarding entry by external port and protocol from an array of port mappings. +* +* @param[in] count - The number of port forwarding entries in the portmap array. +* @param[in] portmap - Pointer to an array of portFwdSingle_t structures containing the port mappings to search. +* @param[in] external_port - The external port number to search for. +* @param[in] proto - The protocol type (TCP, UDP, BOTH_TCP_UDP) to match. +* +* @return The index of the matched entry +* @retval 0 to count-1 - Index of the matched port forwarding entry (0-based) on success. +* @retval -1 - Entry not found. +* +*/ int Utopia_FindPortForwarding (int count, portFwdSingle_t *portmap, int external_port, protocol_t proto); + +/** +* @brief Add a new single port forwarding rule to the configuration. +* \n +* If rule_id is 0, appends the rule at the end. If rule_id is specified, inserts the rule +* \n in order by rule_id, ensuring uniqueness. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] portmap - Pointer to a portFwdSingle_t structure containing the port forwarding rule to add. +* \n Must have valid destination IP address. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_VALUE if rule_id is negative or if rule_id already exists. +* @retval ERR_INVALID_IP if destination IP address is invalid. +* +*/ int Utopia_AddPortForwarding (UtopiaContext *ctx, portFwdSingle_t *portmap); + +/** +* @brief Get a single port forwarding rule by its 0-based index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] index - The 0-based index of the port forwarding rule to retrieve. +* @param[out] fwdinfo - Pointer to a portFwdSingle_t structure where the forwarding rule will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_ITEM_NOT_FOUND if index is out of range. +* +*/ int Utopia_GetPortForwardingByIndex (UtopiaContext *ctx, int index, portFwdSingle_t *fwdinfo); + +/** +* @brief Update a single port forwarding rule at the specified 0-based index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] index - The 0-based index of the port forwarding rule to update. +* @param[in] fwdinfo - Pointer to a portFwdSingle_t structure containing the updated forwarding rule. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_ITEM_NOT_FOUND if index is out of range. +* +*/ int Utopia_SetPortForwardingByIndex (UtopiaContext *ctx, int index, portFwdSingle_t *fwdinfo); + +/** +* @brief Delete a single port forwarding rule at the specified 0-based index. +* \n +* Removes the rule and shifts subsequent rules to fill the gap. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] index - The 0-based index of the port forwarding rule to delete. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_ITEM_NOT_FOUND if index is out of range. +* +*/ int Utopia_DelPortForwardingByIndex (UtopiaContext *ctx, int index); + +/** +* @brief Get a single port forwarding rule by its rule ID. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in,out] fwdinfo - Pointer to a portFwdSingle_t structure. +* \n [in] fwdinfo->rule_id contains the rule ID to search for. +* \n [out] Structure is filled with the matching rule's complete information. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_VALUE if rule_id is negative or if no rule with the specified ID is found. +* +*/ int Utopia_GetPortForwardingByRuleId (UtopiaContext *ctx, portFwdSingle_t *fwdinfo); + +/** +* @brief Update a single port forwarding rule identified by its rule ID. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] fwdinfo - Pointer to a portFwdSingle_t structure containing the updated rule. +* \n fwdinfo->rule_id is used to locate the rule to update. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_VALUE if rule_id is negative. +* @retval ERR_ITEM_NOT_FOUND if no rule with the specified rule_id is found. +* +*/ int Utopia_SetPortForwardingByRuleId (UtopiaContext *ctx, portFwdSingle_t *fwdinfo); + +/** +* @brief Delete a single port forwarding rule identified by its rule ID. +* +* Removes the rule and shifts subsequent rules to fill the gap. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] rule_id - The rule ID of the port forwarding rule to delete. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_ITEM_NOT_FOUND if rule_id is negative or if no rule with the specified ID is found. +* +*/ int Utopia_DelPortForwardingByRuleId (UtopiaContext *ctx, int rule_id); +/** +* @brief Add a dynamic port mapping entry. +* +* Dynamic port mappings do not persist across reboots and are aged out by lease time. +* Automatically updates the last_updated timestamp and firewall rules. +* +* @param[in] portmap - Pointer to a portMapDyn_t structure containing the dynamic port mapping to add. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if portmap is NULL. +* @retval ERR_SYSEVENT_CONN if sysevent connection fails. +* +*/ int Utopia_AddDynPortMapping (portMapDyn_t *portmap); + +/** +* @brief Update an existing dynamic port mapping entry at the specified index. +* \n +* Updates the mapping and refreshes firewall rules. +* +* @param[in] index - The 1-based index of the dynamic port mapping to update. +* @param[in] pmap - Pointer to a portMapDyn_t structure containing the updated mapping information. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if index is out of range. +* @retval ERR_SYSEVENT_CONN if sysevent connection fails. +* +*/ int Utopia_UpdateDynPortMapping (int index, portMapDyn_t *pmap); + +/** +* @brief Delete a dynamic port mapping by searching for a matching entry. +* +* Searches for a mapping matching external host, external port, and protocol, then deletes it. +* +* @param[in] portmap - Pointer to a portMapDyn_t structure containing the mapping to delete. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_ITEM_NOT_FOUND if no matching entry is found. +* @retval ERR_INVALID_ARGS if deletion by index fails. +* @retval ERR_SYSEVENT_CONN if sysevent connection fails. +* +*/ int Utopia_DeleteDynPortMapping (portMapDyn_t *portmap); + +/** +* @brief Delete a dynamic port mapping at the specified index. +* +* Removes the entry and shifts subsequent entries to fill the gap. Updates firewall rules. +* +* @param[in] index - The 1-based index of the dynamic port mapping to delete. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if index is out of range. +* @retval ERR_SYSEVENT_CONN if sysevent connection fails. +* +*/ int Utopia_DeleteDynPortMappingIndex (int index); + +/** +* @brief Remove expired dynamic port mapping entries. +* +* Decrements lease time for all entries by 3600 seconds and removes entries with expired leases. +* This check applies to all entries, and firewall is restarted upon removal. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_SYSEVENT_CONN if sysevent connection fails. +* +*/ int Utopia_InvalidateDynPortMappings (void); + +/** +* @brief Validate a dynamic port mapping by updating its last_updated timestamp. +* \n +* Refreshes the timestamp to extend the lease time of the mapping. +* +* @param[in] index - The 1-based index of the dynamic port mapping to validate. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_SYSEVENT_CONN if sysevent connection fails during retrieval. +* +*/ int Utopia_ValidateDynPortMapping (int index); + +/** +* @brief Get the number of dynamic port mapping entries. +* +* @param[out] count - Pointer to an integer where the dynamic port mapping count will be returned. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_SYSEVENT_CONN if sysevent connection fails. +* +*/ int Utopia_GetDynPortMappingCount (int *count); + +/** +* @brief Get a dynamic port mapping entry at the specified index. +* +* @param[in] index - The 1-based index of the dynamic port mapping to retrieve. +* @param[out] portmap - Pointer to a portMapDyn_t structure where the mapping information will be returned. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_SYSEVENT_CONN if sysevent connection fails. +* @retval ERR_INVALID_VALUE if parsing the mapping entry fails. +* +*/ int Utopia_GetDynPortMapping (int index, portMapDyn_t *portmap); + +/** +* @brief Find a dynamic port mapping entry by external host, port, and protocol. +* +* @param[in] external_host - Pointer to a null-terminated string containing the external host IP address. +* @param[in] external_port - The external port number to search for. +* @param[in] proto - The protocol type (TCP, UDP) to match. +* @param[out] pmap - Pointer to a portMapDyn_t structure where the matching mapping will be returned. +* @param[out] index - Pointer to an integer where the 1-based index of the found entry will be returned. +* +* @return The status of the operation. +* @retval UT_SUCCESS if a matching entry is found. +* @retval ERR_ITEM_NOT_FOUND if no matching entry is found. +* @retval ERR_SYSEVENT_CONN if sysevent connection fails. +* +*/ int Utopia_FindDynPortMapping(const char *external_host, int external_port, protocol_t proto, portMapDyn_t *pmap, int *index); + +/** +* @brief Check if IGD (Internet Gateway Device) user configuration is allowed. +* +* @param[in] ctx - Pointer to the Utopia context. +* +* @return Configuration permission status. +* @retval 1 if IGD user configuration is allowed. +* @retval 0 if disallowed or if ctx is NULL. +* +*/ int Utopia_IGDConfigAllowed (UtopiaContext *ctx); + +/** +* @brief Check if IGD internet disable (using force-termination) is allowed. +* +* @param[in] ctx - Pointer to the Utopia context. +* +* @return Internet disable permission status. +* @retval 1 if IGD internet disable is allowed. +* @retval 0 if disallowed or if ctx is NULL. +* +*/ int Utopia_IGDInternetDisbleAllowed (UtopiaContext *ctx); +/** +* @brief Set the complete list of port forwarding range rules, replacing all existing range rules. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] count - The number of port forwarding range rules in the fwdinfo array. +* @param[in] fwdinfo - Pointer to an array of portFwdRange_t structures containing the range forwarding rules. +* \n If rule_id is 0, it will be auto-assigned based on array position for backward compatibility. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_VALUE if any rule_id is negative. +* @retval ERR_INVALID_IP if any destination IP or public IP address is invalid. +* +*/ int Utopia_SetPortForwardingRange (UtopiaContext *ctx, int count, portFwdRange_t *fwdinfo); + +/** +* @brief Get all configured port forwarding range rules. +* \n +* This function allocates memory for the forwarding range rules array. Caller is responsible for freeing the memory. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] count - Pointer to an integer where the number of range forwarding rules will be returned. +* @param[out] fwdinfo - Pointer to a portFwdRange_t pointer where the allocated array of range forwarding rules will be returned. +* \n Caller must free this memory when done. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful (including when count is 0). +* @retval ERR_INSUFFICIENT_MEM if memory allocation fails. +* @retval ERR_INVALID_PORT_RANGE if parsing a port range fails. +* +*/ int Utopia_GetPortForwardingRange (UtopiaContext *ctx, int *count, portFwdRange_t **fwdinfo); + +/** +* @brief Get the number of configured port forwarding range rules. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] count - Pointer to an integer where the range forwarding rule count will be returned. +* \n Initialized to 0 before retrieval. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_UTCTX_OP_FAILED if Utopia context operation fails. +* @retval ERR_INVALID_INT_VALUE if count is not valid integer. +* +*/ int Utopia_GetPortForwardingRangeCount (UtopiaContext *ctx, int *count); + +/** +* @brief Add a new port forwarding range rule to the configuration. +* +* If rule_id is 0, appends the rule at the end. If rule_id is specified, inserts the rule +* in order by rule_id, ensuring uniqueness. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] portmap - Pointer to a portFwdRange_t structure containing the range forwarding rule to add. +* \n Must have valid destination IP and public IP (if specified) addresses. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_VALUE if rule_id is negative or if rule_id already exists. +* @retval ERR_INVALID_IP if destination IP or public IP address is invalid. +* +*/ int Utopia_AddPortForwardingRange (UtopiaContext *ctx, portFwdRange_t *portmap); + +/** +* @brief Get a port forwarding range rule by its 0-based index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] index - The 0-based index of the range forwarding rule to retrieve. +* @param[out] fwdinfo - Pointer to a portFwdRange_t structure where the forwarding range rule will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_ITEM_NOT_FOUND if index is out of range. +* @retval ERR_INVALID_PORT_RANGE if parsing the port range fails. +* +*/ int Utopia_GetPortForwardingRangeByIndex (UtopiaContext *ctx, int index, portFwdRange_t *fwdinfo); + +/** +* @brief Update a port forwarding range rule at the specified 0-based index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] index - The 0-based index of the range forwarding rule to update. +* @param[in] fwdinfo - Pointer to a portFwdRange_t structure containing the updated range forwarding rule. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_ITEM_NOT_FOUND if index is out of range. +* +*/ int Utopia_SetPortForwardingRangeByIndex (UtopiaContext *ctx, int index, portFwdRange_t *fwdinfo); + +/** +* @brief Delete a port forwarding range rule at the specified 0-based index. +* +* Removes the rule and shifts subsequent rules to fill the gap. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] index - The 0-based index of the range forwarding rule to delete. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_ITEM_NOT_FOUND if index is out of range. +* +*/ int Utopia_DelPortForwardingRangeByIndex (UtopiaContext *ctx, int index); + +/** +* @brief Get a port forwarding range rule by its rule ID. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in,out] fwdinfo - Pointer to a portFwdRange_t structure. +* \n [in] fwdinfo->rule_id contains the rule ID to search for. +* \n [out] Structure is filled with the matching rule's complete information. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_VALUE if rule_id is negative. +* @retval ERR_ITEM_NOT_FOUND if no rule with the specified ID is found. +* @retval ERR_INVALID_PORT_RANGE if parsing the port range fails. +* +*/ int Utopia_GetPortForwardingRangeByRuleId (UtopiaContext *ctx, portFwdRange_t *fwdinfo); + +/** +* @brief Update a port forwarding range rule identified by its rule ID. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] fwdinfo - Pointer to a portFwdRange_t structure containing the updated rule. +* \n fwdinfo->rule_id is used to locate the rule to update. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_VALUE if rule_id is negative. +* @retval ERR_ITEM_NOT_FOUND if no rule with the specified rule_id is found. +* +*/ int Utopia_SetPortForwardingRangeByRuleId (UtopiaContext *ctx, portFwdRange_t *fwdinfo); + +/** +* @brief Delete a port forwarding range rule identified by its rule ID. +* +* Removes the rule and shifts subsequent rules to fill the gap. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] rule_id - The rule ID of the range forwarding rule to delete. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_ITEM_NOT_FOUND if rule_id is negative or if no rule with the specified ID is found. +* +*/ int Utopia_DelPortForwardingRangeByRuleId (UtopiaContext *ctx, int rule_id); +/** +* @brief Set the complete list of port trigger rules, replacing all existing trigger rules. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] count - The number of port trigger rules in the portinfo array. +* @param[in] portinfo - Pointer to an array of portRangeTrig_t structures containing the port trigger rules. +* \n If rule_id is 0, it will be auto-assigned based on array position for backward compatibility. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_VALUE if any rule_id is negative. +* +*/ int Utopia_SetPortTrigger (UtopiaContext *ctx, int count, portRangeTrig_t *portinfo); + +/** +* @brief Get all configured port trigger rules. +* +* This function allocates memory for the port trigger rules array. Caller is responsible for freeing the memory. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] count - Pointer to an integer where the number of port trigger rules will be returned. +* @param[out] portinfo - Pointer to a portRangeTrig_t pointer where the allocated array of trigger rules will be returned. +* \n Caller must free this memory when done. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful (including when count is 0). +* @retval ERR_INSUFFICIENT_MEM if memory allocation fails. +* @retval ERR_INVALID_PORT_RANGE if parsing a port range fails. +* +*/ int Utopia_GetPortTrigger (UtopiaContext *ctx, int *count, portRangeTrig_t **portinfo); + +/** +* @brief Get the number of configured port trigger rules. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] count - Pointer to an integer where the port trigger rule count will be returned. +* \n Initialized to 0 before retrieval. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_UTCTX_OP if utopia get fails +* @retval ERR_INVALID_INT_VALUE if count is not a valid integer +* +*/ int Utopia_GetPortTriggerCount (UtopiaContext *ctx, int *count); + +/** +* @brief Add a new port trigger rule to the configuration. +* \n +* If rule_id is 0, appends the rule at the end. If rule_id is specified, inserts the rule +* \n in order by rule_id, ensuring uniqueness. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] portmap - Pointer to a portRangeTrig_t structure containing the port trigger rule to add. +* \n Includes trigger and forward port ranges with their respective protocols. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_VALUE if rule_id is negative or if rule_id already exists. +* +*/ int Utopia_AddPortTrigger (UtopiaContext *ctx, portRangeTrig_t *portmap); + +/** +* @brief Get a port trigger rule by its 0-based index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] index - The 0-based index of the port trigger rule to retrieve. +* @param[out] fwdinfo - Pointer to a portRangeTrig_t structure where the trigger rule will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_ITEM_NOT_FOUND if index is out of range. +* @retval ERR_INVALID_PORT_RANGE if parsing a port range fails. +* +*/ int Utopia_GetPortTriggerByIndex (UtopiaContext *ctx, int index, portRangeTrig_t *fwdinfo); + +/** +* @brief Update a port trigger rule at the specified 0-based index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] index - The 0-based index of the port trigger rule to update. +* @param[in] fwdinfo - Pointer to a portRangeTrig_t structure containing the updated trigger rule. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_ITEM_NOT_FOUND if index is out of range . +* +*/ int Utopia_SetPortTriggerByIndex (UtopiaContext *ctx, int index, portRangeTrig_t *fwdinfo); + +/** +* @brief Delete a port trigger rule at the specified 0-based index. +* \n +* Removes the rule and shifts subsequent rules to fill the gap. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] index - The 0-based index of the port trigger rule to delete. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_ITEM_NOT_FOUND if index is out of range. +* +*/ int Utopia_DelPortTriggerByIndex (UtopiaContext *ctx, int index); + +/** +* @brief Get a port trigger rule by its rule ID. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in,out] portinfo - Pointer to a portRangeTrig_t structure. +* \n [in] portinfo->rule_id contains the rule ID to search for. +* \n [out] Structure is filled with the matching rule's complete information. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_VALUE if rule_id is negative. +* @retval ERR_ITEM_NOT_FOUND if no rule with the specified ID is found. +* @retval ERR_INVALID_PORT_RANGE if parsing a port range fails. +* +*/ int Utopia_GetPortTriggerByRuleId (UtopiaContext *ctx, portRangeTrig_t *portinfo); + +/** +* @brief Update a port trigger rule identified by its rule ID. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] portinfo - Pointer to a portRangeTrig_t structure containing the updated rule. +* \n portinfo->rule_id is used to locate the rule to update. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_VALUE if rule_id is negative. +* @retval ERR_ITEM_NOT_FOUND if no rule with the specified rule_id is found. +* +*/ int Utopia_SetPortTriggerByRuleId (UtopiaContext *ctx, portRangeTrig_t *portinfo); + +/** +* @brief Delete a port trigger rule identified by its rule ID. +* +* Removes the rule and shifts subsequent rules to fill the gap. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] trigger_id - The rule ID of the port trigger rule to delete. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_ITEM_NOT_FOUND if trigger_id is negative or if no rule with the specified ID is found. +* +*/ int Utopia_DelPortTriggerByRuleId (UtopiaContext *ctx, int trigger_id); +/** +* @brief Set DMZ (Demilitarized Zone) settings. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] dmz - Pointer to a dmz_t structure containing the DMZ settings to be set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or dmz is NULL. +* +*/ int Utopia_SetDMZSettings (UtopiaContext *ctx, dmz_t *dmz); + +/** +* @brief Get DMZ (Demilitarized Zone) settings. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] out_dmz - Pointer to a dmz_t structure where the DMZ settings will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or out_dmz is NULL. +* +*/ int Utopia_GetDMZSettings (UtopiaContext *ctx, dmz_t *out_dmz); +/** +* @brief Add a new Internet Access Policy or update an existing one by policy name. +* +* If a policy with the same name exists, it will be updated. Otherwise, a new policy is appended. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] iap - Pointer to an iap_entry_t structure containing the Internet Access Policy. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or iap is NULL. +* @retval UT_SUCCESS if the policy is successfully added or updated. +* +*/ int Utopia_AddInternetAccessPolicy (UtopiaContext *ctx, iap_entry_t *iap); + +/** +* @brief Edit an existing Internet Access Policy at the specified 1-based index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] index - The 1-based index of the IAP entry to edit. +* @param[in] iap - Pointer to an iap_entry_t structure containing the updated policy information. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx is NULL, iap is NULL, index is less than 1, or index exceeds the policy count. +* +*/ int Utopia_EditInternetAccessPolicy (UtopiaContext *ctx, int index, iap_entry_t *iap); + +/** +* @brief Add or update LAN hosts for an Internet Access Policy identified by policy name. +* \n +* If the policy exists, only the LAN hosts portion is updated. Otherwise, a new policy is created with the specified LAN hosts. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] policyname - Pointer to a null-terminated string containing the policy name. +* @param[in] lanhosts - Pointer to a lanHosts_t structure containing the LAN hosts to associate with the policy. +* \n Includes: IP address list, MAC address list, IP range list. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx, policyname, or lanhosts is NULL. +* +*/ int Utopia_AddInternetAccessPolicyLanHosts (UtopiaContext *ctx, const char *policyname, lanHosts_t *lanhosts); + +/** +* @brief Delete an Internet Access Policy by policy name. +* \n +* Removes the policy and shifts subsequent entries to fill the gap. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] policyname - Pointer to a null-terminated string containing the policy name to delete. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or policyname is NULL. +* @retval ERR_INVALID_VALUE if no policy with the specified name is found. +* +*/ int Utopia_DeleteInternetAccessPolicy (UtopiaContext *ctx, const char *policyname); + +/** +* @brief Get all configured Internet Access Policies. +* +* This function allocates memory for the IAP array. Caller is responsible for freeing the memory. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] out_count - Pointer to an integer where the number of policies will be returned. +* @param[out] out_iap - Pointer to an iap_entry_t pointer where the allocated array of policies will be returned. +* \n Caller must free this memory using Utopia_FreeInternetAccessPolicy when done. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful (including when count is 0). +* @retval ERR_INVALID_ARGS if ctx, out_count, or out_iap is NULL. +* @retval ERR_INSUFFICIENT_MEM if memory allocation fails. +* +*/ int Utopia_GetInternetAccessPolicy (UtopiaContext *ctx, int *out_count, iap_entry_t **out_iap); + +/** +* @brief Find an Internet Access Policy by policy name. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] policyname - Pointer to a null-terminated string containing the policy name to search for. +* @param[out] out_iap - Pointer to an iap_entry_t structure where the matching policy will be returned. +* @param[out] out_index - Optional pointer to an integer where the 1-based index of the found policy will be returned (can be NULL). +* +* @return The status of the operation. +* @retval UT_SUCCESS if a matching policy is found. +* @retval ERR_INVALID_ARGS if ctx, policyname, or out_iap is NULL. +* @retval ERR_ITEM_NOT_FOUND if no policy with the specified name is found. +* +*/ int Utopia_FindInternetAccessPolicy (UtopiaContext *ctx, const char *policyname, iap_entry_t *out_iap, int *out_index); + +/** +* @brief Free memory allocated for an Internet Access Policy entry. +* +* Frees all dynamically allocated memory within the iap_entry_t structure including +* LAN host lists, blocked URL/keyword/application lists, and their associated metadata. +* +* @param[in] iap - Pointer to an iap_entry_t structure to free. +* +* @return void +* +*/ void Utopia_FreeInternetAccessPolicy (iap_entry_t *iap); -/* - * Returns a null terminated array of strings with network - * service names like ftp, telnet, dns, etc - */ + +/** +* @brief Get the list of network service names. +* +* @param[out] out_list - Pointer to a const char pointer where the null-terminated array of service names will be returned. +* \n Includes common services: ftp, telnet, ssh, http, https, smtp, dns, etc. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_GetNetworkServicesList (const char **out_list); typedef struct firewall { @@ -917,7 +2281,32 @@ typedef struct firewall { boolean_t wan_ping_enable_v6; } firewall_t; +/** +* @brief Set firewall settings. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] fw - firewall_t structure containing the firewall settings to be set. +* \n Includes: SPI protection, content filtering, protocol passthrough, WAN access controls. +* \n Supports both IPv4 and IPv6 filtering options. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx is NULL. +* +*/ int Utopia_SetFirewallSettings (UtopiaContext *ctx, firewall_t fw); + +/** +* @brief Get firewall settings. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] fw - Pointer to a firewall_t structure where the firewall settings will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or fw is NULL. +* +*/ int Utopia_GetFirewallSettings (UtopiaContext *ctx, firewall_t *fw); typedef struct ipv6Prefix { @@ -974,7 +2363,30 @@ typedef struct ipv6Info { int ra_provisioning_enable ; /* Whether to listen to RA on the WAN side */ } ipv6Info_t ; +/** +* @brief Set IPv6 settings. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ipv6_info - Pointer to an ipv6Info_t structure containing the IPv6 settings to be set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or ipv6_info is NULL. +* +*/ int Utopia_SetIPv6Settings (UtopiaContext *ctx, ipv6Info_t *ipv6_info); + +/** +* @brief Get IPv6 settings. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] ipv6_info - Pointer to an ipv6Info_t structure where the IPv6 settings will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or ipv6_info is NULL. +* +*/ int Utopia_GetIPv6Settings (UtopiaContext *ctx, ipv6Info_t *ipv6_info); /* @@ -1001,59 +2413,440 @@ typedef struct { boolean_t allow_userconfig; boolean_t allow_wandisable; } igdconf_t; - + +/** +* @brief Restore factory default settings. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_SYSCFG_FAILED if syscfg destroy operation fails. +* +*/ int Utopia_RestoreFactoryDefaults (void); + +/** +* @brief Restore configuration from a backup file. +* +* @param[in] config_fname - Pointer to the configuration filename string. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if config_fname is NULL. +* @retval ERR_INSUFFICIENT_MEM if memory allocation fails. +* @retval ERR_FILE_NOT_FOUND if the configuration file cannot be opened. +* @retval ERR_CFGRESTORE_BAD_MAGIC if the configuration file has invalid magic number. +* @retval ERR_CFGRESTORE_BAD_SIZE if the configuration file size is invalid. +* @retval ERR_CFGRESTORE_BAD_VERSION if the configuration file version is invalid. +* @retval ERR_CFGRESTORE_BAD_CRC32 if the configuration file CRC32 check fails. +* +*/ int Utopia_RestoreConfiguration (char *config_fname); + +/** +* @brief Backup current configuration to a file. +* +* @param[out] out_config_fname - Pointer to a buffer where the output configuration filename will be returned. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_FILE_WRITE_FAILED if the configuration file cannot be written. +* @retval ERR_INSUFFICIENT_MEM if memory allocation fails. +* +*/ int Utopia_BackupConfiguration (char *out_config_fname); + +/** +* @brief Upgrade the device firmware. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] firmware_file - Pointer to the firmware filename string. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or firmware_file is NULL. +* @retval ERR_FILE_WRITE_FAILED if the firmware file cannot be written. +* @retval ERR_FW_UPGRADE_LOCK_CONFLICT if firmware upgrade lock cannot be acquired. +* +*/ int Utopia_FirmwareUpgrade (UtopiaContext *ctx, char *firmware_file); + +/** +* @brief Check if remote management user is allowed to do firmware upgrades +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] http_port - HTTP port number to check. +* +* @return The status of the operation. +* @retval 1 if firmware upgrade is allowed. +* @retval 0 if firmware upgrade is not allowed. + +* @note Checks if the http request is coming from Remote Management (WAN) side by looking at http-port. +*/ int Utopia_IsFirmwareUpgradeAllowed (UtopiaContext *ctx, int http_port); + +/** +* @brief Acquire the firmware upgrade lock. +* +* @param[out] lock_fd - Pointer to an integer where the lock file descriptor will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the lock is acquired successfully. +* @retval ERR_FW_UPGRADE_LOCK_CONFLICT if the lock cannot be acquired. +* @retval ERR_INVALID_ARGS if lock_fd is NULL. +* @retval ERR_FILE_NOT_FOUND if the lock file cannot be opened. +* +*/ int Utopia_AcquireFirmwareUpgradeLock (int *lock_fd); + +/** +* @brief Release the firmware upgrade lock. +* +* @param[in] lock_fd - Lock file descriptor to release. +* +* @return The status of the operation. +* @retval SUCCESS if the lock is released successfully. +* @retval ERR_INVALID_ARGS if lock_fd is invalid. +* @retval ERR_FW_UPGRADE_LOCK_CONFLICT if the lock cannot be acquired. +* +*/ int Utopia_ReleaseFirmwareUpgradeLock (int lock_fd); + +/** +* @brief Check if system changes are allowed. +* +* @return The status of the operation. +* @retval 1 if system changes are allowed. +* @retval 0 if system changes are disallowed. +* +*/ int Utopia_SystemChangesAllowed (void); + +/** +* @brief Reboot the device. +* +* @return The status of the operation. +* @retval SUCCESS if the reboot is initiated successfully. +* @retval ERR_REBOOT_FAILED if the reboot fails. +* +*/ int Utopia_Reboot (void); +/** +* @brief Set the Web UI admin password. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] username - Pointer to the username string. +* @param[in] cleartext_password - Pointer to the cleartext password string. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the password is set successfully. +* @retval ERR_INVALID_ARGS if ctx, username, or cleartext_password is NULL. +* @retval ERR_FILE_NOT_FOUND if the password file cannot be opened. +* @retval ERR_INVALID_VALUE if the username or password is invalid. +* +*/ int Utopia_SetWebUIAdminPasswd (UtopiaContext *ctx, char *username, char *cleartext_password); + +/** +* @brief Check if the admin password is set to the default value. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] is_admin_default - Pointer to a boolean_t where the default status will be returned. +* \n TRUE if admin password is the default value, FALSE otherwise. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or is_admin_default is NULL. +* +*/ int Utopia_IsAdminDefault (UtopiaContext *ctx, boolean_t *is_admin_default); + +/** +* @brief Set Web UI access settings. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ui - Pointer to a webui_t structure containing the Web UI settings to be set. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or ui is NULL. +* +*/ int Utopia_SetWebUISettings (UtopiaContext *ctx, webui_t *ui); + +/** +* @brief Get Web UI access settings. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] ui - Pointer to a webui_t structure where the Web UI settings will be returned. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or ui is NULL. +* +*/ int Utopia_GetWebUISettings (UtopiaContext *ctx, webui_t *ui); +/** +* @brief Set IGD (Internet Gateway Device) configuration settings. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] igd - Pointer to an igdconf_t structure containing the IGD settings to be set. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or igd is NULL. +* +*/ int Utopia_SetIGDSettings (UtopiaContext *ctx, igdconf_t *igd); + +/** +* @brief Get IGD (Internet Gateway Device) configuration settings. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] igd - Pointer to an igdconf_t structure where the IGD settings will be returned. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or igd is NULL. +* +*/ int Utopia_GetIGDSettings (UtopiaContext *ctx, igdconf_t *igd); /* * Logging and Diagnostics */ -/* - * Notes: caller need to free log array - */ + +/** +* @brief Get the incoming traffic log entries. +* +* Retrieves firewall log entries for incoming traffic (WAN to LAN/SELF ACCEPT). +* This function allocates memory for the log array. Caller is responsible for freeing the memory. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] count - Pointer to an integer where the number of log entries will be returned. +* \n Maximum entries: 128. +* @param[out] ilog - Pointer to a logentry_t pointer where the allocated array of log entries will be returned. +* \n Caller must free this memory when done. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful (including when count is 0). +* @retval ERR_INVALID_ARGS if count or ilog is NULL. +* @retval ERR_FILE_NOT_FOUND if the log file cannot be opened. +* @retval other error codes otherwise. +* +*/ int Utopia_GetIncomingTrafficLog (UtopiaContext *ctx, int *count, logentry_t **ilog); -/* - * Notes: caller need to free log array - */ +/** +* @brief Get the outgoing traffic log entries. +* +* Retrieves firewall log entries for outgoing traffic (LAN to WAN ACCEPT). +* This function allocates memory for the log array. Caller is responsible for freeing the memory. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] count - Pointer to an integer where the number of log entries will be returned. +* \n Maximum entries: 64. +* @param[out] olog - Pointer to a logentry_t pointer where the allocated array of log entries will be returned. +* \n Caller must free this memory when done. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful (including when count is 0). +* @retval ERR_INVALID_ARGS if count or olog is NULL. +* @retval ERR_FILE_NOT_FOUND if the log file cannot be opened. +* @retval other error codes otherwise. +* +*/ int Utopia_GetOutgoingTrafficLog (UtopiaContext *ctx, int *count, logentry_t **olog); -/* - * Notes: caller need to free log array - */ +/** +* @brief Get the security log entries. +* \n +* Retrieves firewall log entries for dropped packets (WAN to SELF/ATTACK DROP). +* \n This function allocates memory for the log array. Caller is responsible for freeing the memory. +* +* @param[in] ctx - Pointer to the Utopia context (unused, can be NULL). +* @param[out] count - Pointer to an integer where the number of log entries will be returned. +* \n Maximum entries: 64. +* @param[out] slog - Pointer to a logentry_t pointer where the allocated array of log entries will be returned. +* \n Caller must free this memory when done. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful (including when count is 0). +* @retval ERR_FILE_NOT_FOUND if the log file cannot be opened. +* @retval other error codes otherwise. +* +*/ int Utopia_GetSecurityLog (UtopiaContext *ctx, int *count, logentry_t **slog); +/** +* @brief Get the DHCP client log and save it to a file. +* +* Retrieves DHCP log entries (DISCOVER, OFFER, REQUEST, ACK, NAK, DECLINE, RELEASE, INFORM) and saves to /tmp/dhcp_log.txt. +* +* @param[in] ctx - Pointer to the Utopia context (unused, can be NULL). +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful (including when count is 0). +* @retval ERR_FILE_NOT_FOUND if the log file cannot be opened. +* @retval other error codes otherwise. +* +*/ int Utopia_GetDHCPClientLog (UtopiaContext *ctx); +/** +* @brief Set logging settings. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] log_enabled - Boolean flag to enable or disable logging. +* @param[in] log_viewer - Pointer to log viewer IP address string (can be empty). +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_SetLogSettings (UtopiaContext *ctx, boolean_t log_enabled, char *log_viewer); + +/** +* @brief Get logging settings. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] log_enabled - Pointer to a boolean_t where the logging enabled status will be returned. +* @param[out] log_viewer - Buffer where the log viewer IP address will be returned. +* @param[in] sz - Size of the log_viewer buffer (should be IPHOSTNAME_SZ). +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_GetLogSettings (UtopiaContext *ctx, boolean_t *log_enabled, char *log_viewer, int sz); +/** +* @brief Start a diagnostic ping test. +* +* @param[in] dest - Pointer to the destination IP address or hostname string. +* @param[in] packet_size - Size of the ping packet in bytes (must be > 0). +* @param[in] num_ping - Number of pings to send (0 = indefinite, >= 0). +* \n Results are written to /tmp/.ping_log_tmp. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if dest is NULL, packet_size <= 0, or num_ping < 0. +* +*/ int Utopia_DiagPingTestStart (char *dest, int packet_size, int num_ping); + +/** +* @brief Stop the currently running diagnostic ping test. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_DiagPingTestStop (void); + +/** +* @brief Check if a diagnostic ping test is currently running. +* +* @return Running status. +* @retval 1 if a ping test is running. +* @retval 0 if no ping test is running. +* +*/ int Utopia_DiagPingTestIsRunning (void); + +/** +* @brief Start a diagnostic traceroute test. +* +* @param[in] dest - Pointer to the destination IP address or hostname string. +* \n Results are written to /tmp/.traceroute_log_tmp. +* \n Special handling for 0.0.0.0 and 255.255.255.255 (writes error message). +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if dest is NULL. +* @retval ERR_FILE_NOT_FOUND if the log file cannot be opened for special cases. +* +*/ int Utopia_DiagTracerouteTestStart (char *dest); + +/** +* @brief Stop the currently running diagnostic traceroute test. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_DiagTracerouteTestStop (void); + +/** +* @brief Check if a diagnostic traceroute test is currently running. +* +* @return Running status. +* @retval 1 if a traceroute test is running. +* @retval 0 if no traceroute test is running. +* +*/ int Utopia_DiagTracerouteTestIsRunning (void); +/** +* @brief Execute a diagnostic ping test to a destination host. +* +* This function performs a network connectivity diagnostic test by sending ICMP echo requests (ping) to the specified destination. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] dest - Pointer to the destination IP address or hostname string. +* @param[in] packet_size - Size of the ICMP data payload in bytes. +. +* @param[in] num_ping - Number of ping packets to send. +* +* @return The status of the operation. +* @retval SUCCESS if the ping test is successfully started. +* @retval ERR_INVALID_ARGS if dest is NULL, packet_size <= 0, or num_ping < 0. +* +*/ int diagPingTest (UtopiaContext *ctx, String dest, int packet_size, int num_ping); -int diagTraceroute (UtopiaContext *ctx, String dest, char **results_buffer); +/** +* @brief Execute a diagnostic traceroute test to trace the network path to a destination host. +* +* This function performs a network path diagnostic test by tracing the route packets take to reach the specified destination. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] dest - Pointer to the destination IP address or hostname string. + +* @param[out] results_buffer - Pointer to a char pointer where the traceroute results will be returned. +* \n Caller is responsible for freeing the allocated buffer. +* +* @return The status of the operation. +* @retval SUCCESS if the traceroute test is successfully started. +* @retval ERR_INVALID_ARGS if dest is NULL. +* +*/ +int diagTraceroute (UtopiaContext *ctx, String dest, char **results_buffer); + +/** +* @brief Initiate a PPP connection. +* +* Triggers the wan-start sysevent to start the WAN PPP connection. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_SYSEVENT_CONN if unable to connect to sysevent daemon. +* +*/ int Utopia_PPPConnect (void); + +/** +* @brief Disconnect a PPP connection. +* +* Triggers the wan-stop sysevent to stop the WAN PPP connection. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_SYSEVENT_CONN if unable to connect to sysevent daemon. +* +*/ int Utopia_PPPDisconnect (void); @@ -1080,18 +2873,18 @@ typedef struct byoi { byoi_wanProto_t wan_proto; byoi_wan_ppp_t ppp; hsd_type_t byoi_mode; - boolean_t byoi_bridge_mode; + boolean_t byoi_bridge_mode; }byoi_t; int Utopia_Get_BYOI(UtopiaContext *ctx, byoi_t *byoi); int Utopia_Set_BYOI(UtopiaContext *ctx, byoi_t *byoi); -*/ + #endif typedef enum hsd_type { PRIMARY_PROVIDER_HSD, PRIMARY_PROVIDER_RESTRICTED, USER_SELECTABLE -} hsd_type_t; +} hsd_type_t; typedef enum { @@ -1100,12 +2893,80 @@ typedef enum { NONE } hsdStatus_t; +/** +* @brief Get BYOI (Bring Your Own Internet) allowed status. +* +* This API is used to control to UI pages display +*\n if the status is docsis - no UI page for internet setting. +*\n if the status is non-docsis- UI page with WAN option(byoi) and None( no internet). +*\n if the status is user - UI page with Cable(primary provider), WAN(byoi) and None(no internet) will be provided. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] value - Pointer to an integer where the BYOI allowed state will be returned. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_UTCTX_INIT if ctx is NULL. +* @retval ERR_SYSEVENT_CONN if unable to connect to sysevent daemon. +* +*/ int Utopia_Get_BYOI_allowed(UtopiaContext *ctx, int *value); -int Utopia_Get_BYOI_Current_Provider(UtopiaContext *ctx, hsdStatus_t *hsdStatus); + +/** +* @brief Get the current BYOI provider status. +* \n +* Returns the current HSD mode the user is operating in. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] hsdStatus - Pointer to an hsdStatus_t where the current provider status will be returned. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_UTCTX_INIT if ctx or hsdStatus is NULL. +* @retval ERR_SYSEVENT_CONN if unable to connect to sysevent daemon. +* +*/ +int Utopia_Get_BYOI_Current_Provider(UtopiaContext *ctx, hsdStatus_t *hsdStatus); + +/** +* @brief Set the desired BYOI provider. +* +* Sets the desired HSD mode and triggers sysevent for mode change. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] hsdStatus - The desired provider status to set. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_UTCTX_INIT if ctx is NULL. +* @retval ERR_SYSEVENT_CONN if unable to connect to sysevent daemon. +* +*/ int Utopia_Set_BYOI_Desired_Provider(UtopiaContext *ctx, hsdStatus_t hsdStatus); -/* Web Timeout Config value in minutes*/ +/** +* @brief Get the Web UI timeout value in minutes. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] count - Pointer to an integer where the timeout value (in minutes) will be returned. +* \n Initialized to 0 before retrieval. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_GetWebTimeout(UtopiaContext *ctx, int *count); + +/** +* @brief Set the Web UI timeout value in minutes. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] count - The timeout value (in minutes) to set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_SetWebTimeout(UtopiaContext *ctx, int count); /*typedef enum { @@ -1119,41 +2980,399 @@ typedef struct http_user { //userType_t usertype; } http_user_t; +/** +* @brief Get HTTP home user credentials. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] httpuser - Pointer to an http_user_t structure where the user credentials will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_UTCTX_INIT if ctx or httpuser is NULL. +* +*/ int Utopia_Get_Http_User(UtopiaContext *ctx, http_user_t *httpuser); + +/** +* @brief Set HTTP home user credentials. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] httpuser - Pointer to an http_user_t structure containing the user credentials to set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_Set_Http_User(UtopiaContext *ctx, http_user_t *httpuser); + +/** +* @brief Get HTTP admin credentials. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] httpuser - Pointer to an http_user_t structure where the admin credentials will be returned. + +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_UTCTX_INIT if ctx or httpuser is NULL. +* +*/ int Utopia_Get_Http_Admin(UtopiaContext *ctx, http_user_t *httpuser); + +/** +* @brief Set HTTP admin credentials. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] httpuser - Pointer to an http_user_t structure containing the admin credentials to set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_Set_Http_Admin(UtopiaContext *ctx, http_user_t *httpuser); -int Utopia_Set_Prov_Code(UtopiaContext *ctx, char *val) ; -int Utopia_Get_Prov_Code(UtopiaContext *ctx, char *val) ; + +/** +* @brief Set the provisioning code. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] val - Pointer to the provisioning code string to set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ +int Utopia_Set_Prov_Code(UtopiaContext *ctx, char *val); + +/** +* @brief Get the provisioning code. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] val - Buffer where the provisioning code will be returned (NAME_SZ bytes). +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or val is NULL. +* +*/ +int Utopia_Get_Prov_Code(UtopiaContext *ctx, char *val); + +/** +* @brief Get the device first use date. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] val - Buffer where the first use date will be returned (NAME_SZ bytes). +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or val is NULL. +* +*/ int Utopia_Get_First_Use_Date(UtopiaContext *ctx, char *val); /* NTP Functions */ + +/** +* @brief Set the NTP server address for a specific index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] server - Pointer to the NTP server address string (empty string sets to "no_ntp_address"). +* @param[in] index - NTP server index (1-5). +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_UTCTX_INIT if ctx or server is NULL. +* +*/ int Utopia_Set_DeviceTime_NTPServer(UtopiaContext *ctx, char *server, int index); + +/** +* @brief Get the NTP server address for a specific index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] server - Buffer where the NTP server address will be returned (UTOPIA_TR181_PARAM_SIZE bytes). +* \n Returns empty string if value is "no_ntp_address". +* @param[in] index - NTP server index (1-5). +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_UTCTX_INIT if ctx or server is NULL. +* @retval ERR_SYSCFG_FAILED if syscfg get operation fails. +* +*/ int Utopia_Get_DeviceTime_NTPServer(UtopiaContext *ctx, char *server,int index); + +/** +* @brief Set the local timezone. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] tz - Pointer to the timezone string. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_UTCTX_INIT if ctx or tz is NULL. +* +*/ int Utopia_Set_DeviceTime_LocalTZ(UtopiaContext *ctx, char *tz); + +/** +* @brief Get the local timezone. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] tz - Buffer where the timezone will be returned (UTOPIA_TR181_PARAM_SIZE1 bytes). +* \n Buffer is zeroed before retrieval. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_UTCTX_INIT if ctx or tz is NULL. +* @retval ERR_SYSCFG_FAILED if syscfg get operation fails. +* +*/ int Utopia_Get_DeviceTime_LocalTZ(UtopiaContext *ctx, char *tz); + +/** +* @brief Enable or disable NTP time synchronization. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] enable - Enable flag (TRUE/FALSE). +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_UTCTX_INIT if ctx is NULL. +* +*/ int Utopia_Set_DeviceTime_Enable(UtopiaContext *ctx, unsigned char enable); + +/** +* @brief Get NTP time synchronization enabled status. +* +* @param[in] ctx - Pointer to the Utopia context. +* +* @return NTP enabled status. +* @retval TRUE if NTP is enabled. +* @retval FALSE if NTP is disabled or ctx is NULL. +* +*/ unsigned char Utopia_Get_DeviceTime_Enable(UtopiaContext *ctx); + +/** +* @brief Get the NTP synchronization status. +* +* @param[in] ctx - Pointer to the Utopia context. +* +* @return NTP synchronization status. +* @retval 0 or positive integer representing the status. +* +*/ int Utopia_Get_DeviceTime_Status(UtopiaContext *ctx); + +/** +* @brief Enable or disable daylight saving time. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] enable - Enable flag (TRUE/FALSE). +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_UTCTX_INIT if ctx is NULL. +* +*/ int Utopia_Set_DeviceTime_DaylightEnable(UtopiaContext *ctx, unsigned char enable); + +/** +* @brief Get daylight saving time enabled status. +* +* @param[in] ctx - Pointer to the Utopia context. +* +* @return Daylight saving time enabled status. +* @retval TRUE if daylight saving time is enabled. +* @retval FALSE if daylight saving time is disabled or ctx is NULL. +* +*/ unsigned char Utopia_Get_DeviceTime_DaylightEnable(UtopiaContext *ctx); + +/** +* @brief Get the daylight saving time offset in minutes. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] count - Pointer to an integer where the daylight offset (in minutes) will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_Get_DeviceTime_DaylightOffset(UtopiaContext *ctx, int *count); + +/** +* @brief Set the daylight saving time offset in minutes. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] count - The daylight offset value (in minutes) to set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_Set_DeviceTime_DaylightOffset(UtopiaContext *ctx, int count); +/** +* @brief Get the management WAN MAC address. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] val - Buffer where the MAC address will be returned (MACADDR_SZ bytes). +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or val is NULL. +* +*/ int Utopia_Get_Mac_MgWan(UtopiaContext *ctx, char *val); +/** +* @brief Get the list of MAC addresses of devices associated with an Ethernet port. +* \n +* Queries the switch for learned MAC addresses on the specified port. +* +* @param[in] unitId - Switch unit ID. +* @param[in] portId - Switch port ID. +* @param[out] macAddrList - Buffer where MAC addresses will be returned (6 bytes per address). +* \n Multicast MAC addresses are excluded. +* @param[out] numMacAddr - Pointer to an integer where the number of associated devices will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_FILE_OPEN_FAIL if the temporary file cannot be opened. +* @retval ERR_FILE_CLOSE_FAIL if the temporary file cannot be closed. +* @retval ERR_NO_NODES if macAddrList is NULL. +* +*/ int Utopia_GetEthAssocDevices(int unitId, int portId, unsigned char *macAddrList,int *numMacAddr); +/** +* @brief Get the count of LAN management interfaces. +* +* @param[in] ctx - Pointer to the Utopia context (unused). +* @param[out] val - Pointer to an integer where the LAN interface count will be returned. +* \n Currently always returns 1 (single LAN interface supported). +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_GetLanMngmCount(UtopiaContext *ctx, int *val); + +/** +* @brief Set the LAN management instance number. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] val - Instance number to set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_VALUE if the value cannot be set. +* +*/ int Utopia_SetLanMngmInsNum(UtopiaContext *ctx, unsigned long int val); + +/** +* @brief Get the LAN management instance number. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] val - Pointer to an unsigned long int where the instance number will be returned. +* \n Returns 0 if not configured. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_GetLanMngmInsNum(UtopiaContext *ctx, unsigned long int *val); + +/** +* @brief Get the LAN management alias. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] buf - Buffer where the alias will be returned. +* @param[in] b_len - Size of the buffer. +* \n If alias doesn't exist, returns the LAN interface name and sets it as the alias. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_VALUE if buf is NULL. +* +*/ int Utopia_GetLanMngmAlias(UtopiaContext *ctx, char *buf, size_t b_len ); + +/** +* @brief Set the LAN management alias. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] val - Pointer to the alias string to set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_VALUE if val is NULL or value cannot be set. +* +*/ int Utopia_SetLanMngmAlias(UtopiaContext *ctx, const char *val); //int Utopia_GetLanMngmLanMode(UtopiaContext *ctx, lanMngm_LanMode_t *LanMode); //int Utopia_SetLanMngmLanMode(UtopiaContext *ctx, lanMngm_LanMode_t LanMode); + +/** +* @brief Get LAN networks allow setting. +* +* USGv2 platform does not support this feature. +* +* @param[in] ctx - Pointer to the Utopia context . +* @param[out] allow - Pointer to an integer where the allow setting will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_GetLanMngmLanNetworksAllow(UtopiaContext *ctx, int* allow); + +/** +* @brief Set LAN networks allow setting. +* \n +* USGv2 platform does not support this feature. +* +* @param[in] ctx - Pointer to the Utopia context . +* @param[in] allow - Allow setting (must be 0, other values are invalid). +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful (allow == 0). +* @retval ERR_INVALID_VALUE if allow != 0. +* +*/ int Utopia_SetLanMngmLanNetworksAllow(UtopiaContext *ctx, int allow); + +/** +* @brief Get LAN NAPT (Network Address Port Translation) mode. +* +* Retrieves the current NAT mode for the LAN interface. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] enable - Pointer to a napt_mode_t where the NAPT mode will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or enable is NULL. +* +*/ int Utopia_GetLanMngmLanNapt(UtopiaContext *ctx, napt_mode_t *enable); + +/** +* @brief Set LAN NAPT (Network Address Port Translation) mode. +* +* Sets the NAT mode for the LAN interface. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] enable - NAPT mode to set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx is NULL. +* +*/ int Utopia_SetLanMngmLanNapt(UtopiaContext *ctx, napt_mode_t enable); #define DNS_CLIENT_NAMESERVER_CNT 10 @@ -1162,11 +3381,82 @@ typedef struct dns_client{ char dns_server[DNS_CLIENT_NAMESERVER_CNT][IPADDR_SZ]; }DNS_Client_t; +/** +* @brief Set DNS client enable status. +* +* DNS client cannot be disabled on this platform. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] enable - Enable flag (must be TRUE, FALSE is invalid). +* +* @return The status of the operation. +* @retval SUCCESS if enable is TRUE. +* @retval ERR_INVALID_VALUE if enable is FALSE. +* +*/ int Utopia_SetDNSEnable(UtopiaContext *ctx, boolean_t enable); + +/** +* @brief Get DNS client enable status. +* +* DNS client is always enabled on this platform. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] enable - Pointer to a boolean_t where the enable status will be returned. +* \n Always returns TRUE. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_GetDNSEnable(UtopiaContext *ctx, boolean_t* enable); + +/** +* @brief Get the list of DNS servers from /etc/resolv.conf. +* \n +* Parses the resolv.conf file to retrieve configured DNS servers. +* +* @param[in] ctx - Pointer to the Utopia context (unused). +* @param[out] dns - Pointer to a DNS_Client_t structure where the DNS servers will be returned. +* \n Maximum 10 DNS servers (DNS_CLIENT_NAMESERVER_CNT). +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_VALUE if dns is NULL. +* @retval ERR_FILE_NOT_FOUND if /etc/resolv.conf cannot be opened. +* +*/ int Utopia_GetDNSServer(UtopiaContext *ctx, DNS_Client_t * dns); +/** +* @brief Add or remove iptables rules for ephemeral (dynamic) port forwarding. +* +* Manages iptables NAT and filter rules for dynamic port mappings based on system state. +* +* @param[in] pmap - Pointer to a portMapDyn_t structure containing the port mapping information. +* @param[in] isCallForAdd - Boolean flag indicating operation type. +* \n TRUE: Add iptables rules (operation code 'A'). +* \n FALSE: Delete iptables rules (operation code 'D'). +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_SYSEVENT_CONN if unable to connect to sysevent daemon. +* @retval ERR_INVALID_VALUE if pmap->enabled is FALSE. +* +*/ int Utopia_IPRule_ephemeral_port_forwarding( portMapDyn_t *pmap, boolean_t isCallForAdd ); + +/** +* @brief Check if an IP address is within the DHCP address range. +* +* @param[in] ip_to_check - Pointer to the IP address string to check. +* \n Compared against dhcp_start and dhcp_end values from syscfg. +* +* @return Check result. +* @retval 1 if IP is within DHCP range, IP is NULL/empty, or parsing fails. +* @retval 0 if IP is outside DHCP range. +* +*/ int Utopia_privateIpCheck(char *ip_to_check); #if defined(DDNS_BROADBANDFORUM) @@ -1183,12 +3473,100 @@ typedef struct DynamicDnsClient boolean_t Enable; }DynamicDnsClient_t; +/** +* @brief Get the instance number of a Dynamic DNS client by index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] uIndex - 0-based index of the Dynamic DNS client. +* @param[out] ins - Pointer to an integer where the instance number will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_GetDynamicDnsClientInsNumByIndex(UtopiaContext *ctx, unsigned long uIndex, int *ins); + +/** +* @brief Get the total number of Dynamic DNS clients. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] num - Pointer to an integer where the client count will be returned. +* \n Value is cached in static variable g_DynamicDnsClientCount. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_GetNumberOfDynamicDnsClient(UtopiaContext *ctx, int *num); + +/** +* @brief Get a Dynamic DNS client entry by 0-based index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulIndex - 0-based index of the Dynamic DNS client. +* @param[out] DynamicDnsClient - Pointer to a DynamicDnsClient_t structure where the client information will be returned. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int Utopia_GetDynamicDnsClientByIndex(UtopiaContext *ctx, unsigned long ulIndex, DynamicDnsClient_t *DynamicDnsClient); + +/** +* @brief Update a Dynamic DNS client entry at the specified 0-based index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulIndex - 0-based index of the Dynamic DNS client to update. +* @param[in] DynamicDnsClient - Pointer to a DynamicDnsClient_t structure containing the updated client information. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int Utopia_SetDynamicDnsClientByIndex(UtopiaContext *ctx, unsigned long ulIndex, const DynamicDnsClient_t *DynamicDnsClient); + +/** +* @brief Set the instance number and alias for a Dynamic DNS client at the specified 0-based index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulIndex - 0-based index of the Dynamic DNS client. +* @param[in] ins - Instance number to set. +* @param[in] alias - Pointer to the alias string to set. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int Utopia_SetDynamicDnsClientInsAndAliasByIndex(UtopiaContext *ctx, unsigned long ulIndex, unsigned long ins, const char *alias); + +/** +* @brief Add a new Dynamic DNS client entry. +* +* Increments the client count and adds the entry at the next available index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] DynamicDnsClient - Pointer to a DynamicDnsClient_t structure containing the client information to add. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int Utopia_AddDynamicDnsClient(UtopiaContext *ctx, const DynamicDnsClient_t *DynamicDnsClient); + +/** +* @brief Delete a Dynamic DNS client entry by instance number. +* +* Searches for the client by instance number, removes it, and shifts subsequent entries. +* Decrements the client count. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ins - Instance number of the Dynamic DNS client to delete. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* @retval -1 if no client with the specified instance number is found. +* +*/ int Utopia_DelDynamicDnsClient(UtopiaContext *ctx, unsigned long ins); #endif diff --git a/source/utapi/lib/utapi_dslite.h b/source/utapi/lib/utapi_dslite.h index e55a6a2b..542bc0b9 100644 --- a/source/utapi/lib/utapi_dslite.h +++ b/source/utapi/lib/utapi_dslite.h @@ -18,6 +18,7 @@ #define __UTAPI_TR_DSLITE_H__ #define STR_SZ 257 + #define MAX_NUM_INSTANCES 255 typedef struct @@ -41,20 +42,210 @@ DsLiteCfg char tunnel_v4addr[64+1]; }DsLiteCfg_t; +/** + * @brief Get DS-Lite global enable status. + * + * Retrieves the global enable/disable state for DS-Lite functionality from Utopia context. + * + * @param[in] ctx - Pointer to Utopia context + * @param[out] bEnabled - Pointer to boolean to receive enable status + * \n TRUE if DS-Lite is enabled + * \n FALSE if DS-Lite is disabled + * + * @return The status of the operation. + * @retval SUCCESS - Enable status retrieved successfully + * + */ int Utopia_GetDsliteEnable(UtopiaContext *ctx, boolean_t *bEnabled); + +/** + * @brief Set DS-Lite global enable status. + * + * Configures the global enable/disable state for DS-Lite functionality in Utopia context. + * + * @param[in] ctx - Pointer to Utopia context + * @param[in] bEnabled - Enable flag to set + * \n TRUE to enable DS-Lite + * \n FALSE to disable DS-Lite + * + * @return The status of the operation. + * @retval SUCCESS - Enable status set successfully + * + */ int Utopia_SetDsliteEnable(UtopiaContext *ctx, boolean_t bEnabled); + +/** + * @brief Get number of DS-Lite tunnel entries. + * + * Retrieves the count of configured DS-Lite tunnel entries from Utopia context. + * + * @param[in] ctx - Pointer to Utopia context + * @param[out] cnt - Pointer to unsigned long to receive entry count + * \n Valid range: 0 to MAX_NUM_INSTANCES (255) + * + * @return The status of the operation. + * @retval SUCCESS - Entry count retrieved successfully + * + */ int Utopia_GetNumOfDsliteEntries(UtopiaContext *ctx,unsigned long *cnt); + +/** + * @brief Set number of DS-Lite tunnel entries. + * + * Updates the count of configured DS-Lite tunnel entries in Utopia context. + * + * @param[in] ctx - Pointer to Utopia context + * @param[in] cnt - Number of DS-Lite entries + * \n Valid range: 0 to MAX_NUM_INSTANCES (255) + * + * @return The status of the operation. + * @retval SUCCESS - Entry count set successfully + * + */ int Utopia_SetNumOfDsliteEntries(UtopiaContext *ctx,unsigned long cnt); + +/** + * @brief Get DS-Lite tunnel configuration by instance number. + * + * Retrieves configuration for a specific DS-Lite tunnel entry identified by instance number. + * Uses g_IndexMapDslite[] to map instance number to index, then calls Utopia_GetDsliteByIndex(). + * + * @param[in] ctx - Pointer to Utopia context + * @param[in,out] pDsliteCfg - Pointer to DsLiteCfg_t structure + * \n Input: InstanceNumber field must be set (non-zero) + * \n Output: All configuration fields populated + * + * @return The status of the operation. + * @retval SUCCESS - Configuration retrieved successfully + * @retval ERR_INVALID_ARGS - ctx or pDsliteCfg is NULL, or InstanceNumber is 0 + * + */ int Utopia_GetDsliteCfg(UtopiaContext *ctx,DsLiteCfg_t *pDsliteCfg); + +/** + * @brief Set DS-Lite tunnel configuration by instance number. + * + * Stores configuration for a specific DS-Lite tunnel entry identified by instance number. + * Uses g_IndexMapDslite[] to map instance number to index, then calls Utopia_SetDsliteByIndex(). + * + * @param[in] ctx - Pointer to Utopia context + * @param[in] pDsliteCfg - Pointer to DsLiteCfg_t structure with configuration to set + * \n InstanceNumber field must be set (non-zero) + * + * @return The status of the operation. + * @retval SUCCESS - Configuration stored successfully + * @retval ERR_INVALID_ARGS - ctx or pDsliteCfg is NULL, or InstanceNumber is 0 + * + */ int Utopia_SetDsliteCfg(UtopiaContext *ctx,DsLiteCfg_t *pDsliteCfg); + +/** + * @brief Add a new DS-Lite tunnel entry. + * + * Creates a new DS-Lite tunnel configuration entry with the specified parameters. + * Assigns the next available index, updates the entry count, and stores the configuration. + * + * @param[in] ctx - Pointer to Utopia context + * @param[in] pDsliteCfg - Pointer to DsLiteCfg_t structure with new entry configuration + * \n InstanceNumber field must be set (non-zero) + * + * @return The status of the operation. + * @retval SUCCESS - Entry added successfully + * @retval ERR_INVALID_ARGS - ctx or pDsliteCfg is NULL, or InstanceNumber is 0 + * + */ int Utopia_AddDsliteEntry(UtopiaContext *ctx, DsLiteCfg_t *pDsliteCfg); + +/** + * @brief Delete a DS-Lite tunnel entry by instance number. + * + * Removes a DS-Lite tunnel configuration entry and compacts the entry list. + * All entries after the deleted entry are shifted down by one index. + * + * @param[in] ctx - Pointer to Utopia context + * @param[in] ulInstanceNumber - Instance number of entry to delete + * \n Valid range: 1 to MAX_NUM_INSTANCES (255) + * + * @return The status of the operation. + * @retval SUCCESS - Entry deleted successfully + * @retval ERR_INVALID_ARGS - ctx is NULL or ulInstanceNumber is 0 + * + */ int Utopia_DelDsliteEntry(UtopiaContext *ctx, unsigned long ulInstanceNumber); +/** + * @brief Get DS-Lite entry by zero-based index. + * + * Retrieves DS-Lite configuration for the entry at the specified index position. + * If instance number exists at this index, updates g_IndexMapDslite[] mapping. + * + * @param[in] ctx - Pointer to Utopia context + * @param[in] ulIndex - Zero-based index of entry to retrieve + * \n Valid range: 0 to (entry_count - 1) + * @param[out] pDsliteEntry - Pointer to DsLiteCfg_t structure to receive configuration + * \n Cast from void* for generic interface + * + * @return The status of the operation. + * @retval SUCCESS - Entry retrieved successfully + * @retval ERR_INVALID_ARGS - ctx or pDsliteEntry is NULL + * + */ int Utopia_GetDsliteEntry(UtopiaContext *ctx,unsigned long ulIndex, void *pDsliteEntry); + +/** + * @brief Set DS-Lite instance number for a specific index. + * + * Associates an instance number with a zero-based index position and updates + * the g_IndexMapDslite[] mapping. + * + * @param[in] ctx - Pointer to Utopia context + * @param[in] ulIndex - Zero-based index position + * \n Valid range: 0 to (MAX_NUM_INSTANCES - 1) + * @param[in] ulInstanceNumber - Instance number to assign + * \n Valid range: 1 to MAX_NUM_INSTANCES (255) + * + * @return The status of the operation. + * @retval SUCCESS - Instance number set successfully + * @retval ERR_INVALID_ARGS - ctx is NULL + * + */ int Utopia_SetDsliteInsNum(UtopiaContext *ctx, unsigned long ulIndex, unsigned long ulInstanceNumber); /* Utility functions */ + +/** + * @brief Get DS-Lite configuration by zero-based index (utility function). + * + * Low-level utility function that retrieves all DS-Lite configuration parameters + * from Utopia context for the entry at the specified index. Reads both configurable + * and read-only parameters. + * + * @param[in] ctx - Pointer to Utopia context + * @param[in] ulIndex - Zero-based index of entry to retrieve + * \n Valid range: 0 to (entry_count - 1) + * @param[out] pDsLiteCfg_t - Pointer to DsLiteCfg_t structure to receive all configuration fields + * + * @return The status of the operation. + * @retval SUCCESS - Configuration retrieved successfully + * + */ int Utopia_GetDsliteByIndex(UtopiaContext *ctx, unsigned long ulIndex, DsLiteCfg_t *pDsLiteCfg_t); + +/** + * @brief Set DS-Lite configuration by zero-based index (utility function). + * + * Low-level utility function that stores DS-Lite configuration parameters to Utopia context + * for the entry at the specified index. Writes only configurable parameters (not read-only). + * + * @param[in] ctx - Pointer to Utopia context + * @param[in] ulIndex - Zero-based index of entry to update + * \n Valid range: 0 to (entry_count - 1) + * @param[in] pDsLiteCfg_t - Pointer to DsLiteCfg_t structure with configuration to store + * + * @return The status of the operation. + * @retval SUCCESS - Configuration stored successfully + * + */ int Utopia_SetDsliteByIndex(UtopiaContext *ctx, unsigned long ulIndex, DsLiteCfg_t *pDsLiteCfg_t); #endif // __UTAPI_TR_DSLITE_H__ diff --git a/source/utapi/lib/utapi_parental_control.h b/source/utapi/lib/utapi_parental_control.h index b67fdc23..28f66249 100644 --- a/source/utapi/lib/utapi_parental_control.h +++ b/source/utapi/lib/utapi_parental_control.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -48,7 +48,28 @@ typedef struct mng_devs boolean_t allow_all; //If true, all the devices is allowed to connect to the network except for those devices with md_dev.is_block set to true. Vice versa. } mng_devs_t; +/** +* @brief Get the managed devices configuration. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] mng_devs - Pointer to a mng_devs_t structure where the managed devices configuration will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_GetMngDevsCfg(UtopiaContext *ctx, mng_devs_t *mng_devs); + +/** +* @brief Set the managed devices configuration. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] mng_devs - Pointer to a mng_devs_t structure containing the managed devices configuration to be set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_SetMngDevsCfg(UtopiaContext *ctx, const mng_devs_t *mng_devs); //---------------------------------------------------------------- @@ -68,14 +89,117 @@ typedef struct blkurl #endif }blkurl_t; +/** +* @brief Get the blocked URL configuration status. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] enable - Pointer to an integer where the enable status will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_GetBlkURLCfg(UtopiaContext *ctx, int *enable); + +/** +* @brief Set the blocked URL configuration status. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] enable - Enable status to be set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_SetBlkURLCfg(UtopiaContext *ctx, const int enable); + +/** +* @brief Get the instance number of a blocked URL entry by index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] uIndex - Index of the blocked URL entry. +* @param[out] ins - Pointer to an integer where the instance number will be returned. +* +* @return The status of the operation. +* +*/ int Utopia_GetBlkURLInsNumByIndex(UtopiaContext *ctx, unsigned long uIndex, int *ins); + +/** +* @brief Get the total number of blocked URL entries. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] num - Pointer to an integer where the count will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_GetNumberOfBlkURL(UtopiaContext *ctx, int *num); + +/** +* @brief Get a blocked URL entry by index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulIndex - Index of the blocked URL entry. +* @param[out] blkurl - Pointer to a blkurl_t structure where the blocked URL data will be returned. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int Utopia_GetBlkURLByIndex(UtopiaContext *ctx, unsigned long ulIndex, blkurl_t *blkurl); + +/** +* @brief Set a blocked URL entry by index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulIndex - Index of the blocked URL entry. +* @param[in] blkurl - Pointer to a blkurl_t structure containing the blocked URL data to be set. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int Utopia_SetBlkURLByIndex(UtopiaContext *ctx, unsigned long ulIndex, const blkurl_t *blkurl); + +/** +* @brief Set instance number and alias for a blocked URL entry by index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulIndex - Index of the blocked URL entry. +* @param[in] ins - Instance number to be set. +* @param[in] alias - Pointer to the alias string to be set. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int Utopia_SetBlkURLInsAndAliasByIndex(UtopiaContext *ctx, unsigned long ulIndex, unsigned long ins, const char *alias); + +/** +* @brief Add a new blocked URL entry. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] blkurl - Pointer to a blkurl_t structure containing the blocked URL data to be added. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int Utopia_AddBlkURL(UtopiaContext *ctx, const blkurl_t *blkurl); + +/** +* @brief Delete a blocked URL entry by instance number. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ins - Instance number of the blocked URL entry to be deleted. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* @retval -1 if the entry is out of range. +* +*/ int Utopia_DelBlkURL(UtopiaContext *ctx, unsigned long ins); //-------------------------------------------------------------------- @@ -90,12 +214,94 @@ typedef struct trusted_user char ipaddr[64]; }trusted_user_t; +/** +* @brief Get the instance number of a trusted user entry by index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] uIndex - Index of the trusted user entry. +* @param[out] ins - Pointer to an integer where the instance number will be returned. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int Utopia_GetTrustedUserInsNumByIndex(UtopiaContext *ctx, unsigned long uIndex, int *ins); + +/** +* @brief Get the total number of trusted user entries. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] num - Pointer to an integer where the count will be returned. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int Utopia_GetNumberOfTrustedUser(UtopiaContext *ctx, int *num); + +/** +* @brief Get a trusted user entry by index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulIndex - Index of the trusted user entry. +* @param[out] trusted_user - Pointer to a trusted_user_t structure where the trusted user data will be returned. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int Utopia_GetTrustedUserByIndex(UtopiaContext *ctx, unsigned long ulIndex, trusted_user_t *trusted_user); + +/** +* @brief Set a trusted user entry by index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulIndex - Index of the trusted user entry. +* @param[in] trusted_user - Pointer to a trusted_user_t structure containing the trusted user data to be set. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int Utopia_SetTrustedUserByIndex(UtopiaContext *ctx, unsigned long ulIndex, const trusted_user_t *trusted_user); + +/** +* @brief Set instance number and alias for a trusted user entry by index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulIndex - Index of the trusted user entry. +* @param[in] ins - Instance number to be set. +* @param[in] alias - Pointer to the alias string to be set. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int Utopia_SetTrustedUserInsAndAliasByIndex(UtopiaContext *ctx, unsigned long ulIndex, int ins, const char *alias); + +/** +* @brief Add a new trusted user entry. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] trusted_user - Pointer to a trusted_user_t structure containing the trusted user data to be added. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int Utopia_AddTrustedUser(UtopiaContext *ctx, const trusted_user_t *trusted_user); + +/** +* @brief Delete a trusted user entry by instance number. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ins - Instance number of the trusted user entry to be deleted. +* +* @return The status of the operation. +* @retval -1 if the entry is out of range. +* @retval 0 if the operation is successful. +* +*/ int Utopia_DelTrustedUser(UtopiaContext *ctx, unsigned long ins); //---------------------------------------------------------------------- @@ -115,14 +321,118 @@ typedef struct ms_serv }ms_serv_t; +/** +* @brief Get the managed services configuration status. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] enable - Pointer to an integer where the enable status will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_GetMngServsCfg(UtopiaContext *ctx, int *enable); + +/** +* @brief Set the managed services configuration status. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] enable - Enable status to be set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_SetMngServsCfg(UtopiaContext *ctx, const int enable); + +/** +* @brief Get the instance number of a managed service entry by index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] uIndex - Index of the managed service entry. +* @param[out] ins - Pointer to an integer where the instance number will be returned. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int Utopia_GetMSServInsNumByIndex(UtopiaContext *ctx, unsigned long uIndex, int *ins); + +/** +* @brief Get the total number of managed service entries. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] num - Pointer to an integer where the count will be returned. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int Utopia_GetNumberOfMSServ(UtopiaContext *ctx, int *num); + +/** +* @brief Get a managed service entry by index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulIndex - Index of the managed service entry. +* @param[out] ms_serv - Pointer to a ms_serv_t structure where the managed service data will be returned. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int Utopia_GetMSServByIndex(UtopiaContext *ctx, unsigned long ulIndex, ms_serv_t *ms_serv); + +/** +* @brief Set a managed service entry by index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulIndex - Index of the managed service entry. +* @param[in] ms_serv - Pointer to a ms_serv_t structure containing the managed service data to be set. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int Utopia_SetMSServByIndex(UtopiaContext *ctx, unsigned long ulIndex, const ms_serv_t *ms_serv); + +/** +* @brief Set instance number and alias for a managed service entry by index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulIndex - Index of the managed service entry. +* @param[in] ins - Instance number to be set. +* @param[in] alias - Pointer to the alias string to be set. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int Utopia_SetMSServInsAndAliasByIndex(UtopiaContext *ctx, unsigned long ulIndex, int ins, const char *alias); + +/** +* @brief Add a new managed service entry. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ms_serv - Pointer to a ms_serv_t structure containing the managed service data to be added. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int Utopia_AddMSServ(UtopiaContext *ctx, const ms_serv_t *ms_serv); + +/** +* @brief Delete a managed service entry by instance number. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ins - Instance number of the managed service entry to be deleted. +* +* @return The status of the operation. +* @retval -1 if the entry is out of range. +* @retval 0 if the operation is successful. +* +*/ int Utopia_DelMSServ(UtopiaContext *ctx, unsigned long ins); //---------------------------------------------------------------------- @@ -136,13 +446,95 @@ typedef struct ms_trusteduser unsigned char ipaddrtype; // 4 or 6 char ipaddr[64]; }ms_trusteduser_t; - + +/** +* @brief Get the instance number of a managed services trusted user entry by index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] uIndex - Index of the managed services trusted user entry. +* @param[out] ins - Pointer to an integer where the instance number will be returned. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int Utopia_GetMSTrustedUserInsNumByIndex(UtopiaContext *ctx, unsigned long uIndex, int *ins); + +/** +* @brief Get the total number of managed services trusted user entries. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] num - Pointer to an integer where the count will be returned. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int Utopia_GetNumberOfMSTrustedUser(UtopiaContext *ctx, int *num); + +/** +* @brief Get a managed services trusted user entry by index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulIndex - Index of the managed services trusted user entry. +* @param[out] ms_trusteduser - Pointer to a ms_trusteduser_t structure where the managed services trusted user data will be returned. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int Utopia_GetMSTrustedUserByIndex(UtopiaContext *ctx, unsigned long ulIndex, ms_trusteduser_t *ms_trusteduser); + +/** +* @brief Set a managed services trusted user entry by index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulIndex - Index of the managed services trusted user entry. +* @param[in] ms_trusteduser - Pointer to a ms_trusteduser_t structure containing the managed services trusted user data to be set. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int Utopia_SetMSTrustedUserByIndex(UtopiaContext *ctx, unsigned long ulIndex, const ms_trusteduser_t *ms_trusteduser); + +/** +* @brief Set instance number and alias for a managed services trusted user entry by index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulIndex - Index of the managed services trusted user entry. +* @param[in] ins - Instance number to be set. +* @param[in] alias - Pointer to the alias string to be set. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int Utopia_SetMSTrustedUserInsAndAliasByIndex(UtopiaContext *ctx, unsigned long ulIndex, int ins, const char *alias); + +/** +* @brief Add a new managed services trusted user entry. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ms_trusteduser - Pointer to a ms_trusteduser_t structure containing the managed services trusted user data to be added. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int Utopia_AddMSTrustedUser(UtopiaContext *ctx, const ms_trusteduser_t *ms_trusteduser); + +/** +* @brief Delete a managed services trusted user entry by instance number. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ins - Instance number of the managed services trusted user entry to be deleted. +* +* @return The status of the operation. +* @retval -1 if the entry is out of range. +* @retval 0 if the operation is successful. +* +*/ int Utopia_DelMSTrustedUser(UtopiaContext *ctx, unsigned long ins); //------------------------------------------------------------------- @@ -159,13 +551,95 @@ typedef struct md_dev char end_time[64]; char block_days[64]; }md_dev_t; - + +/** +* @brief Get the instance number of a managed device entry by index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] uIndex - Index of the managed device entry. +* @param[out] ins - Pointer to an integer where the instance number will be returned. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int Utopia_GetMDDevInsNumByIndex(UtopiaContext *ctx, unsigned long uIndex, int *ins); + +/** +* @brief Get the total number of managed device entries. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] num - Pointer to an integer where the count will be returned. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int Utopia_GetNumberOfMDDev(UtopiaContext *ctx, int *num); + +/** +* @brief Get a managed device entry by index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulIndex - Index of the managed device entry. +* @param[out] md_dev - Pointer to a md_dev_t structure where the managed device data will be returned. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int Utopia_GetMDDevByIndex(UtopiaContext *ctx, unsigned long ulIndex, md_dev_t *md_dev); + +/** +* @brief Set a managed device entry by index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulIndex - Index of the managed device entry. +* @param[in] md_dev - Pointer to a md_dev_t structure containing the managed device data to be set. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int Utopia_SetMDDevByIndex(UtopiaContext *ctx, unsigned long ulIndex, const md_dev_t *md_dev); + +/** +* @brief Set instance number and alias for a managed device entry by index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulIndex - Index of the managed device entry. +* @param[in] ins - Instance number to be set. +* @param[in] alias - Pointer to the alias string to be set. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int Utopia_SetMDDevInsAndAliasByIndex(UtopiaContext *ctx, unsigned long ulIndex, int ins, const char *alias); + +/** +* @brief Add a new managed device entry. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] md_dev - Pointer to a md_dev_t structure containing the managed device data to be added. +* +* @return The status of the operation. +* @retval 0 if the operation is successful. +* +*/ int Utopia_AddMDDev(UtopiaContext *ctx, const md_dev_t *md_dev); + +/** +* @brief Delete a managed device entry by instance number. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ins - Instance number of the managed device entry to be deleted. +* +* @return The status of the operation. +* @retval -1 if the entry is out of range. +* @retval 0 if the operation is successful. +* +*/ int Utopia_DelMDDev(UtopiaContext *ctx, unsigned long ins); #ifdef __cplusplus diff --git a/source/utapi/lib/utapi_tr_dhcp.h b/source/utapi/lib/utapi_tr_dhcp.h index 311dceea..a2cb79a7 100644 --- a/source/utapi/lib/utapi_tr_dhcp.h +++ b/source/utapi/lib/utapi_tr_dhcp.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -37,7 +37,7 @@ #define __UTAPI_TR_DHCP_H__ #include -#define STR_SZ 64 +#define STR_SZ 64 #define MAX_NUM_INSTANCES 255 #define DHCPV4_NUM_SERVER_POOLS 1 @@ -78,7 +78,7 @@ dhcpV4ServerPoolCfg char Alias[64]; unsigned char bEnabled; unsigned long Order; - char Interface[64]; + char Interface[64]; char VendorClassID[256]; unsigned char VendorClassIDExclude; unsigned int VendorClassIDMode; @@ -137,28 +137,227 @@ dhcpV4ServerPoolStaticAddress /* Function prototypes */ +/** +* @brief Get the DHCPv4 server enable status. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] bEnabled - Pointer to an unsigned char where the enable status will be returned. +* \n FALSE (0) if disabled, TRUE (non-zero) if enabled. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_GetDhcpServerEnable(UtopiaContext *ctx, unsigned char *bEnabled); + +/** +* @brief Set the DHCPv4 server enable status. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] bEnabled - Enable status to be set. +* \n FALSE (0) to disable, TRUE (non-zero) to enable. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_SetDhcpServerEnable(UtopiaContext *ctx, unsigned char bEnabled); +/** +* @brief Get the total number of DHCPv4 server pools. +* +* @return The number of DHCPv4 server pools. +* @retval DHCPV4_NUM_SERVER_POOLS The fixed number of server pools supported. +* +*/ int Utopia_GetNumberOfDhcpV4ServerPools(); +/** +* @brief Get a DHCPv4 server pool entry by index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulIndex - Index of the DHCPv4 server pool entry. +* @param[out] pEntry - Pointer to a dhcpV4ServerPoolEntry_t structure where the pool entry data will be returned. +* \n The structure includes both configuration and information components. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or pEntry is NULL. +* +*/ int Utopia_GetDhcpV4ServerPoolEntry(UtopiaContext *ctx,unsigned long ulIndex, void *pEntry); + +/** +* @brief Get the DHCPv4 server pool configuration. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] pCfg - Pointer to a dhcpV4ServerPoolCfg_t structure where the pool configuration will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or pCfg is NULL. +* +*/ int Utopia_GetDhcpV4ServerPoolCfg(UtopiaContext *ctx,void *pCfg); + +/** +* @brief Get the DHCPv4 server pool information. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulInstanceNumber - Instance number of the DHCPv4 server pool. +* @param[out] pInfo - Pointer to a dhcpV4ServerPoolInfo_t structure where the pool information will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or pInfo is NULL. +* @retval ERR_SYSEVENT_CONN if unable to connect to sysevent. +* +*/ int Utopia_GetDhcpV4ServerPoolInfo(UtopiaContext *ctx, unsigned long ulInstanceNumber, void *pInfo); +/** +* @brief Set the DHCPv4 server pool configuration. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] pCfg - Pointer to a dhcpV4ServerPoolCfg_t structure containing the pool configuration to be set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or pCfg is NULL. +* +*/ int Utopia_SetDhcpV4ServerPoolCfg(UtopiaContext *ctx, void *pCfg); + +/** +* @brief Set the instance number and alias for a DHCPv4 server pool. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulIndex - Index of the DHCPv4 server pool. +* @param[in] ulInstanceNumber - Instance number to be set. +* @param[in] pAlias - Pointer to the alias string to be set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or pAlias is NULL. +* +*/ int Utopia_SetDhcpV4ServerPoolValues(UtopiaContext *ctx, unsigned long ulIndex, unsigned long ulInstanceNumber, char *pAlias); +/** +* @brief Get the number of static address entries in a DHCPv4 server pool. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulPoolInstanceNumber - Instance number of the DHCPv4 server pool. +* +* @return The number of static address entries in the pool. +* +*/ int Utopia_GetDhcpV4SPool_NumOfStaticAddress(UtopiaContext *ctx,unsigned long ulPoolInstanceNumber); + +/** +* @brief Get a static address entry from a DHCPv4 server pool by index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulPoolInstanceNumber - Instance number of the DHCPv4 server pool. +* @param[in] ulIndex - Index of the static address entry. +* @param[out] pSAddr - Pointer to a dhcpV4ServerPoolStaticAddress_t structure where the static address data will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or pSAddr is NULL, or if instance number exceeds MAX_NUM_INSTANCES. +* +*/ int Utopia_GetDhcpV4SPool_SAddress(UtopiaContext *ctx, unsigned long ulPoolInstanceNumber,unsigned long ulIndex, void *pSAddr); + +/** +* @brief Get a static address entry from a DHCPv4 server pool by instance number. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulClientInstanceNumber - Instance number of the client. +* @param[in,out] pSAddr - Pointer to a dhcpV4ServerPoolStaticAddress_t structure. +* \n [in] The InstanceNumber field must be set to the instance number to retrieve. +* \n [out] The structure will be populated with the static address data. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or pSAddr is NULL, or if InstanceNumber is 0. +* +*/ int Utopia_GetDhcpV4SPool_SAddressByInsNum(UtopiaContext *ctx, unsigned long ulClientInstanceNumber, void *pSAddr); +/** +* @brief Add a new static address entry to a DHCPv4 server pool. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulPoolInstanceNumber - Instance number of the DHCPv4 server pool. +* @param[in] pSAddr - Pointer to a dhcpV4ServerPoolStaticAddress_t structure containing the static address data to be added. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or pSAddr is NULL, instance number is 0, MAC address is invalid, +* IP address is invalid, or IP/MAC already exists in the list. +* +*/ int Utopia_AddDhcpV4SPool_SAddress(UtopiaContext *ctx, unsigned long ulPoolInstanceNumber, void *pSAddr); + +/** +* @brief Delete a static address entry from a DHCPv4 server pool. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulPoolInstanceNumber - Instance number of the DHCPv4 server pool. +* @param[in] ulInstanceNumber - Instance number of the static address entry to be deleted. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx is NULL or instance number is 0. +* +*/ int Utopia_DelDhcp4SPool_SAddress(UtopiaContext *ctx, unsigned long ulPoolInstanceNumber, unsigned long ulInstanceNumber); +/** +* @brief Set a static address entry in a DHCPv4 server pool. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulPoolInstanceNumber - Instance number of the DHCPv4 server pool. +* @param[in] pSAddr - Pointer to a dhcpV4ServerPoolStaticAddress_t structure containing the static address data to be set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx is NULL or instance number is 0. +* +*/ int Utopia_SetDhcpV4SPool_SAddress(UtopiaContext *ctx, unsigned long ulPoolInstanceNumber, void *pSAddr); + +/** +* @brief Set the instance number and alias for a static address entry in a DHCPv4 server pool. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulPoolInstanceNumber - Instance number of the DHCPv4 server pool. +* @param[in] ulIndex - Index of the static address entry. +* @param[in] ulInstanceNumber - Instance number to be set. +* @param[in] pAlias - Pointer to the alias string to be set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or pAlias is NULL. +* +*/ int Utopia_SetDhcpV4SPool_SAddress_Values(UtopiaContext *ctx, unsigned long ulPoolInstanceNumber, unsigned long ulIndex, unsigned long ulInstanceNumber, char *pAlias); /* Utility Functions */ +/** +* @brief Get a static address entry from a DHCPv4 server pool by index (utility function). +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulIndex - Index of the static address entry. +* @param[out] pSAddr_t - Pointer to a dhcpV4ServerPoolStaticAddress_t structure where the static address data will be returned. +* \n The structure includes instance number, alias, enable status, MAC address, +* \n IP address, device name, comments, and active flag. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval 1 if error occurs. +* +*/ int Utopia_GetDhcpV4SPool_SAddressByIndex(UtopiaContext *ctx, unsigned long ulIndex, dhcpV4ServerPoolStaticAddress_t *pSAddr_t); #endif // __UTAPI_TR_DHCP_H__ diff --git a/source/utapi/lib/utapi_tr_user.h b/source/utapi/lib/utapi_tr_user.h index 65af7cff..722152fe 100644 --- a/source/utapi/lib/utapi_tr_user.h +++ b/source/utapi/lib/utapi_tr_user.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -50,7 +50,7 @@ _USER_ACCESS_PERMISSIONS USER_ADMIN = 1, USER_HOMEUSER, USER_RESTRICTED, - USER_DENIED + USER_DENIED }USER_ACCESS_PERMISSIONS; @@ -80,20 +80,142 @@ userCfg /* Function prototypes */ +/** +* @brief Get the total number of user accounts. +* +* @param[in] ctx - Pointer to the Utopia context. +* +* @return The number of user accounts. +* @retval The number of user accounts on success. +* @retval ERR_INVALID_ARGS if ctx is NULL. +* +*/ int Utopia_GetNumOfUsers(UtopiaContext *ctx); + +/** +* @brief Set the total number of user accounts. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] count - The number of user accounts to be set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx is NULL. +* +*/ int Utopia_SetNumOfUsers(UtopiaContext *ctx, int count); +/** +* @brief Get a user entry by index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulIndex - Index of the user entry (0-based). +* @param[out] pUserEntry - Pointer to a userCfg_t structure where the user entry data will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or pUserEntry is NULL. +* +*/ int Utopia_GetUserEntry(UtopiaContext *ctx,unsigned long ulIndex, void *pUserEntry); + +/** +* @brief Get a user configuration by instance number. +* +* @param[in,out] ctx - Pointer to the Utopia context. +* @param[in,out] pUserCfg - Pointer to a userCfg_t structure. +* \n [in] The InstanceNumber field must be set to the instance number to retrieve. +* \n [out] The structure will be populated with the user configuration data. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or pUserCfg is NULL, or if InstanceNumber is 0. +* +*/ int Utopia_GetUserCfg(UtopiaContext *ctx,void *pUserCfg); +/** +* @brief Set a user configuration by instance number. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] pUserCfg - Pointer to a userCfg_t structure containing the user configuration to be set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or pUserCfg is NULL, or if InstanceNumber is 0. +* +*/ int Utopia_SetUserCfg(UtopiaContext *ctx, void *pUserCfg); + +/** +* @brief Set the instance number for a user entry at a given index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulIndex - Index of the user entry (0-based). +* @param[in] ulInstanceNumber - Instance number to be set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx is NULL. +* +*/ int Utopia_SetUserValues(UtopiaContext *ctx, unsigned long ulIndex, unsigned long ulInstanceNumber); +/** +* @brief Add a new user account. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] pUserCfg - Pointer to a userCfg_t structure containing the user configuration to be added. +* \n The InstanceNumber field must be valid (non-zero). +* \n The user count will be incremented automatically. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or pUserCfg is NULL, or if InstanceNumber is 0. +* +*/ int Utopia_AddUser(UtopiaContext *ctx, void *pUserCfg); + +/** +* @brief Delete a user account by instance number. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulInstanceNumber - Instance number of the user account to be deleted. +* \n If the user is enabled and has remote access capability, +* \n the user will also be removed from the Linux system using deluser command. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx is NULL or if InstanceNumber is 0. +* +*/ int Utopia_DelUser(UtopiaContext *ctx, unsigned long ulInstanceNumber); /* Utility functions */ +/** +* @brief Get a user configuration by index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulIndex - Index of the user entry (0-based). +* @param[out] pUserCfg_t - Pointer to a userCfg_t structure where the user configuration will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_GetUserByIndex(UtopiaContext *ctx, unsigned long ulIndex, userCfg_t *pUserCfg_t); + +/** +* @brief Set a user configuration by index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulIndex - Index of the user entry (0-based). +* @param[in] pUserCfg_t - Pointer to a userCfg_t structure containing the user configuration to be set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_SetUserByIndex(UtopiaContext *ctx, unsigned long ulIndex, userCfg_t *pUserCfg_t); #endif // __UTAPI_TR_USER_H__ diff --git a/source/utapi/lib/utapi_tr_wlan.h b/source/utapi/lib/utapi_tr_wlan.h index 2aa65739..073bf56d 100644 --- a/source/utapi/lib/utapi_tr_wlan.h +++ b/source/utapi/lib/utapi_tr_wlan.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -229,7 +229,7 @@ wifiRadioDinfo }wifiRadioDinfo_t; /* - * WiFi Radio Entry + * WiFi Radio Entry */ typedef struct @@ -242,7 +242,7 @@ wifiRadioEntry }wifiRadioEntry_t; /* - * WiFi Radio Stats + * WiFi Radio Stats */ typedef struct @@ -411,11 +411,11 @@ typedef struct wifiAPAssocDevice { unsigned char MacAddress[6]; - unsigned char AuthenticationState; + unsigned char AuthenticationState; unsigned long LastDataDownlinkRate; unsigned long LastDataUplinkRate; int SignalStrength; - unsigned long Retransmissions; + unsigned long Retransmissions; unsigned char Active; }wifiAPAssocDevice_t; @@ -423,7 +423,7 @@ wifiAPAssocDevice * * Mac Filter Cfg * */ -typedef struct +typedef struct wifiMacFilterCfg { unsigned char macFilterEnabled; @@ -434,71 +434,674 @@ wifiMacFilterCfg /* Function Definitions */ +/** +* @brief Get the total number of WiFi radio instances. +* +* @return The number of WiFi radio instances. +* @retval WIFI_RADIO_NUM_INSTANCES The fixed number of radio instances supported. +* +*/ int Utopia_GetWifiRadioInstances(); + +/** +* @brief Get a WiFi radio entry by index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulIndex - Index of the WiFi radio entry (0-based). +* \n Valid range: 0 to (WIFI_RADIO_NUM_INSTANCES - 1). +* @param[out] pEntry - Pointer to a wifiRadioEntry_t structure where the radio entry data will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or pEntry is NULL. +* +*/ int Utopia_GetWifiRadioEntry(UtopiaContext *ctx, unsigned long ulIndex, void *pEntry); +/** +* @brief Get the WiFi radio configuration by index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulIndex - Index of the WiFi radio (0-based). +* \n Valid range: 0 to (WIFI_RADIO_NUM_INSTANCES - 1). +* @param[out] cfg - Pointer to a wifiRadioCfg_t structure where the radio configuration will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or cfg is NULL, or if ulIndex is out of range. +* +*/ int Utopia_GetIndexedWifiRadioCfg(UtopiaContext *ctx, unsigned long ulIndex, void *cfg); + +/** +* @brief Get the WiFi radio configuration by instance number. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] dummyInstanceNum - If non-zero, sets InstanceNumber to 0 in the output structure. +* @param[in,out] cfg - Pointer to a wifiRadioCfg_t structure. +* \n [in] The InstanceNumber field must be set. +* \n [out] The structure will be populated with the radio configuration. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or cfg is NULL, or if the mapped index is out of range. +* @retval ERR_GENERAL if generic error. +* @retval ERR_NO_NODES if no configuration nodes are found. +* +*/ int Utopia_GetWifiRadioCfg(UtopiaContext *ctx,int dummyInstanceNum, void *cfg); + +/** +* @brief Get the WiFi radio static information by index. +* +* @param[in] ulIndex - Index of the WiFi radio (0-based). +* \n Valid range: 0 to (WIFI_RADIO_NUM_INSTANCES - 1). +* @param[out] sInfo - Pointer to a wifiRadioSinfo_t structure where the static information will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if sInfo is NULL or if ulIndex is out of range. +* +*/ int Utopia_GetWifiRadioSinfo(unsigned long ulIndex, void *sInfo); + +/** +* @brief Get the WiFi radio dynamic information by index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulIndex - Index of the WiFi radio (0-based). +* \n Valid range: 0 to (WIFI_RADIO_NUM_INSTANCES - 1). +* @param[out] dInfo - Pointer to a wifiRadioDinfo_t structure where the dynamic information will be returned. +* \n The information includes status, last change timestamp, and channels in use. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or dInfo is NULL, or if ulIndex is out of range. +* +*/ int Utopia_GetIndexedWifiRadioDinfo(UtopiaContext *ctx, unsigned long ulIndex, void *dInfo); + +/** +* @brief Get the WiFi radio dynamic information by instance number. +* +* @param[in] ulInstanceNum - Instance number of the WiFi radio. +* @param[out] dInfo - Pointer to a wifiRadioDinfo_t structure where the dynamic information will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if dInfo is NULL or if the mapped index is out of range. +* @retval ERR_NO_NODES if no information nodes are found. +* +*/ int Utopia_GetWifiRadioDinfo(unsigned long ulInstanceNum, void *dInfo); +/** +* @brief Set the WiFi radio configuration. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] cfg - Pointer to a wifiRadioCfg_t structure containing the radio configuration to be set. +* \n The InstanceNumber field must be valid. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or cfg is NULL, or if the mapped index is out of range. +* +*/ int Utopia_SetWifiRadioCfg(UtopiaContext *ctx, void *cfg); + +/** +* @brief Set the instance number and alias for a WiFi radio. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulIndex - Index of the WiFi radio (0-based). +* \n Valid range: 0 to (WIFI_RADIO_NUM_INSTANCES - 1). +* @param[in] ulInstanceNum - Instance number to be set. +* @param[in] pAlias - Pointer to the alias string to be set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or pAlias is NULL, or if ulIndex is out of range. +* +*/ int Utopia_WifiRadioSetValues(UtopiaContext *ctx, unsigned long ulIndex, unsigned long ulInstanceNum, char *pAlias); +/** +* @brief Get the WiFi radio statistics by instance number. +* +* @param[in] ulInstanceNum - Instance number of the WiFi radio. +* @param[out] stats - Pointer to a wifiRadioStats_t structure where the statistics will be returned. +* \n Statistics include bytes sent/received, packets sent/received, +* \n errors sent/received, and discarded packets sent/received. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if stats is NULL or if the mapped index is out of range. +* @retval ERR_GENERAL if generic error. +* @retval ERR_NO_NODES if no statistics nodes are found. +* +*/ int Utopia_GetWifiRadioStats(unsigned long ulInstanceNum, void *stats); +/** +* @brief Get the total number of WiFi SSID instances. +* +* @param[in] ctx - Pointer to the Utopia context. +* +* @return The number of WiFi SSID instances. +* @retval The number of WiFi SSID instances on success. +* @retval ERR_INVALID_ARGS if ctx is NULL. +* +*/ int Utopia_GetWifiSSIDInstances(UtopiaContext *ctx); + +/** +* @brief Get a WiFi SSID entry by index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulIndex - Index of the WiFi SSID entry (0-based). +* @param[out] pEntry - Pointer to a wifiSSIDEntry_t structure where the SSID entry data will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or pEntry is NULL. +* +*/ int Utopia_GetWifiSSIDEntry(UtopiaContext *ctx, unsigned long ulIndex, void *pEntry); +/** +* @brief Get the WiFi SSID configuration by index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulIndex - Index of the WiFi SSID (0-based). +* @param[out] cfg - Pointer to a wifiSSIDCfg_t structure where the SSID configuration will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or cfg is NULL. +* +*/ int Utopia_GetIndexedWifiSSIDCfg(UtopiaContext *ctx, unsigned long ulIndex, void *cfg); + +/** +* @brief Get the WiFi SSID configuration by instance number. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] dummyInstanceNum - If non-zero, sets InstanceNumber to 0 in the output structure. +* @param[in,out] cfg - Pointer to a wifiSSIDCfg_t structure. +* \n [in] The InstanceNumber field must be set. +* \n [out] The structure will be populated with the SSID configuration. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or cfg is NULL. +* @retval ERR_GENERAL if generic error. +* @retval ERR_NO_NODES if no configuration nodes are found. +* +*/ int Utopia_GetWifiSSIDCfg(UtopiaContext *ctx, int dummyInstanceNum, void *cfg); + +/** +* @brief Get the WiFi SSID static information by index. +* +* @param[in] ulIndex - Index of the WiFi SSID (0-based). +* @param[out] sInfo - Pointer to a wifiSSIDSInfo_t structure where the static information will be returned. +* \n The information includes name, BSSID, and MAC address. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if sInfo is NULL. +* @retval ERR_GENERAL if generic error. +* @retval ERR_NO_NODES if no information nodes are found. +* +*/ int Utopia_GetWifiSSIDSInfo(unsigned long ulIndex, void *sInfo); + +/** +* @brief Get the WiFi SSID dynamic information by instance number. +* +* @param[in] ulInstanceNum - Instance number of the WiFi SSID. +* @param[out] dInfo - Pointer to a wifiSSIDDInfo_t structure where the dynamic information will be returned. +* \n The information includes status and last change timestamp. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if dInfo is NULL. +* @retval ERR_GENERAL if generic error. +* @retval ERR_NO_NODES if no information nodes are found. +* +*/ int Utopia_GetWifiSSIDDInfo(unsigned long ulInstanceNum, void *dInfo); + +/** +* @brief Get the WiFi SSID dynamic information by index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulIndex - Index of the WiFi SSID (0-based). +* @param[out] dInfo - Pointer to a wifiSSIDDInfo_t structure where the dynamic information will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or dInfo is NULL. +* +*/ int Utopia_GetIndexedWifiSSIDDInfo(UtopiaContext *ctx, unsigned long ulIndex, void *dInfo); + +/** +* @brief Get the WiFi SSID dynamic information by instance number. +* +* @param[in] ulInstanceNum - Instance number of the WiFi SSID. +* @param[out] dInfo - Pointer to a wifiSSIDDInfo_t structure where the dynamic information will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if dInfo is NULL. +* +*/ int Utopia_GetWifiSSIDDinfo(unsigned long ulInstanceNum, void *dInfo); +/** +* @brief Set the WiFi SSID configuration. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] cfg - Pointer to a wifiSSIDCfg_t structure containing the SSID configuration to be set. +* \n The InstanceNumber field must be valid. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or cfg is NULL. +* +*/ int Utopia_SetWifiSSIDCfg(UtopiaContext *ctx, void *cfg); + +/** +* @brief Set the instance number and alias for a WiFi SSID. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulIndex - Index of the WiFi SSID (0-based). +* @param[in] ulInstanceNum - Instance number to be set. +* @param[in] pAlias - Pointer to the alias string to be set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or pAlias is NULL. +* +*/ int Utopia_WifiSSIDSetValues(UtopiaContext *ctx, unsigned long ulIndex, unsigned long ulInstanceNum, char *pAlias); +/** +* @brief Get the WiFi SSID statistics by instance number. +* +* @param[in] ulInstanceNum - Instance number of the WiFi SSID. +* @param[out] stats - Pointer to a wifiSSIDStats_t structure where the statistics will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if stats is NULL. +* +*/ int Utopia_GetWifiSSIDStats(unsigned long ulInstanceNum, void *stats); +/** +* @brief Get the total number of WiFi access point instances. +* +* @param[in] ctx - Pointer to the Utopia context. +* +* @return The number of WiFi access point instances. +* @retval The number of WiFi access point instances on success. +* @retval ERR_INVALID_ARGS if ctx is NULL. +* +*/ int Utopia_GetWifiAPInstances(UtopiaContext *ctx); + +/** +* @brief Get a WiFi access point entry by SSID name. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] pSSID - Pointer to the SSID name string. +* @param[out] pEntry - Pointer to a wifiAPEntry_t structure where the access point entry data will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx, pSSID, or pEntry is NULL. +* +*/ int Utopia_GetWifiAPEntry(UtopiaContext *ctx, char*pSSID, void *pEntry); +/** +* @brief Get the WiFi access point configuration by index. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulIndex - Index of the WiFi access point (0-based). +* @param[out] pCfg - Pointer to a wifiAPCfg_t structure where the access point configuration will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or pCfg is NULL. +* +*/ int Utopia_GetIndexedWifiAPCfg(UtopiaContext *ctx, unsigned long ulIndex, void *pCfg); + +/** +* @brief Get the WiFi access point configuration by instance number. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] dummyInstanceNum - If non-zero, sets InstanceNumber to 0 in the output structure. +* @param[in,out] cfg - Pointer to a wifiAPCfg_t structure. +* \n [in] The InstanceNumber field must be set. +* \n [out] The structure will be populated with the access point configuration. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or cfg is NULL. +* @retval ERR_GENERAL if generic error. +* @retval ERR_NO_NODES if no configuration nodes are found. +* +*/ int Utopia_GetWifiAPCfg(UtopiaContext *ctx, int dummyInstanceNum, void *cfg); + +/** +* @brief Get the WiFi access point information by SSID name. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] pSSID - Pointer to the SSID name string. +* @param[out] info - Pointer to a wifiAPInfo_t structure where the access point information will be returned. +* \n The information includes status, WMM capability, and UAPSD capability. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx, pSSID, or info is NULL. +* @retval ERR_GENERAL if generic error. +* @retval ERR_NO_NODES if no information nodes are found. +* +*/ int Utopia_GetWifiAPInfo(UtopiaContext *ctx, char *pSSID, void *info); +/** +* @brief Set the WiFi access point configuration. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] cfg - Pointer to a wifiAPCfg_t structure containing the access point configuration to be set. +* \n The InstanceNumber field must be valid. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or cfg is NULL. +* +*/ int Utopia_SetWifiAPCfg(UtopiaContext *ctx, void *cfg); + +/** +* @brief Set the instance number and alias for a WiFi access point. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ulIndex - Index of the WiFi access point (0-based). +* @param[in] ulInstanceNum - Instance number to be set. +* @param[in] pAlias - Pointer to the alias string to be set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or pAlias is NULL. +* +*/ int Utopia_WifiAPSetValues(UtopiaContext *ctx, unsigned long ulIndex, unsigned long ulInstanceNum, char *pAlias); +/** +* @brief Get the WiFi access point security entry by SSID name. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] pSSID - Pointer to the SSID name string. +* @param[out] pEntry - Pointer to a wifiAPSecEntry_t structure where the security entry data will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx, pSSID, or pEntry is NULL. +* +*/ int Utopia_GetWifiAPSecEntry(UtopiaContext *ctx, char*pSSID, void *pEntry); + +/** +* @brief Get the WiFi access point security configuration by SSID name. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] pSSID - Pointer to the SSID name string. +* @param[out] cfg - Pointer to a wifiAPSecCfg_t structure where the security configuration will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx, pSSID, or cfg is NULL. +* @retval ERR_GENERAL if generic error. +* @retval ERR_NO_NODES if no configuration nodes are found. +* +*/ int Utopia_GetWifiAPSecCfg(UtopiaContext *ctx, char*pSSID, void *cfg); + +/** +* @brief Get the WiFi access point security information by SSID name. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] pSSID - Pointer to the SSID name string. +* @param[out] info - Pointer to a wifiAPSecInfo_t structure where the security information will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx, pSSID, or info is NULL. + +* +*/ int Utopia_GetWifiAPSecInfo(UtopiaContext *ctx, char *pSSID, void *info); +/** +* @brief Set the WiFi access point security configuration by SSID name. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] pSSID - Pointer to the SSID name string. +* @param[in] cfg - Pointer to a wifiAPSecCfg_t structure containing the security configuration to be set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx, pSSID, or cfg is NULL. + +* +*/ int Utopia_SetWifiAPSecCfg(UtopiaContext *ctx,char *pSSID, void *cfg); +/** +* @brief Get the WiFi access point WPS entry by SSID name. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] pSSID - Pointer to the SSID name string. +* @param[out] pEntry - Pointer to a wifiAPWPSEntry_t structure where the WPS entry data will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx, pSSID, or pEntry is NULL. +* +*/ int Utopia_GetWifiAPWPSEntry(UtopiaContext *ctx, char*pSSID, void *pEntry); + +/** +* @brief Get the WiFi access point WPS configuration by SSID name. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] pSSID - Pointer to the SSID name string. +* @param[out] cfg - Pointer to a wifiAPWPSCfg_t structure where the WPS configuration will be returned. +* \n The configuration includes enable status and config methods enabled (bitmask of wifiWPSMethod_t). +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx, pSSID, or cfg is NULL. +* +*/ int Utopia_GetWifiAPWPSCfg(UtopiaContext *ctx, char*pSSID, void *cfg); +/** +* @brief Set the WiFi access point WPS configuration by SSID name. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] pSSID - Pointer to the SSID name string. +* @param[in] cfg - Pointer to a wifiAPWPSCfg_t structure containing the WPS configuration to be set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx, pSSID, or cfg is NULL. +* +*/ int Utopia_SetWifiAPWPSCfg(UtopiaContext *ctx,char *pSSID, void *cfg); +/** +* @brief Get the count of associated devices for a WiFi access point by SSID name. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] pSSID - Pointer to the SSID name string. +* +* @return The number of associated devices. +* @retval The count of associated devices on success. +* @retval ERR_INVALID_ARGS if ctx or pSSID is NULL. +* @retval ERR_NO_NODES if no device nodes are found. +* @retval ERR_GENERAL if generic error. +* +*/ unsigned long Utopia_GetAssociatedDevicesCount(UtopiaContext *ctx, char *pSSID); + +/** +* @brief Get an associated device information by index for a WiFi access point. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] pSSID - Pointer to the SSID name string. +* @param[in] ulIndex - Index of the associated device (0-based). +* @param[out] assocDev - Pointer to a wifiAPAssocDevice_t structure where the device information will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx, pSSID, or assocDev is NULL. +* @retval ERR_GENERAL if generic error. +* @retval ERR_NO_NODES if no device nodes are found. +* +*/ int Utopia_GetAssocDevice(UtopiaContext *ctx, char *pSSID, unsigned long ulIndex, void *assocDev); +/** +* @brief Get the WiFi access point index by SSID name. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] pSSID - Pointer to the SSID name string. +* +* @return The access point index. +* @retval The access point index on success. +* @retval ERR_INVALID_ARGS if ctx or pSSID is NULL. +* @retval ERR_SSID_NOT_FOUND if the SSID is not found. +* +*/ unsigned long Utopia_GetWifiAPIndex(UtopiaContext *ctx, char *pSSID); /*MF */ +/** +* @brief Get the WiFi access point MAC filter configuration by SSID name. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] pSSID - Pointer to the SSID name string. +* @param[out] cfg - Pointer to a wifiMacFilterCfg_t structure where the MAC filter configuration will be returned. +* \n The configuration includes enable status, filter mode, number of MAC addresses, +* \n and the MAC address list (up to 50 addresses). +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx, pSSID, or cfg is NULL. +* @retval ERR_GENERAL if generic error. +* @retval ERR_NO_NODES if no configuration nodes are found. +* +*/ int Utopia_GetWifiAPMFCfg(UtopiaContext *ctx, char *pSSID, void *cfg); + +/** +* @brief Set the WiFi access point MAC filter configuration by SSID name. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] pSSID - Pointer to the SSID name string. +* @param[in] cfg - Pointer to a wifiMacFilterCfg_t structure containing the MAC filter configuration to be set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx, pSSID, or cfg is NULL. +* +*/ int Utopia_SetWifiAPMFCfg(UtopiaContext *ctx, char *pSSID, void *cfg); /* Utility functions */ +/** +* @brief Find the instance number corresponding to an index. +* +* @param[in] ulIndex - Index to search for. +* @param[in] numArray - Pointer to the number array to search in. +* @param[in] numArrayLen - Length of the number array. +* +* @return The instance number found at the given index. +* @retval The instance number on success. +* @retval 0 if instance number not found. +* +*/ unsigned long instanceNum_find(unsigned long ulIndex, int *numArray, int numArrayLen); + +/** +* @brief Parse /proc/net/dev file for a specific interface field. +* +* @param[in] if_name - Pointer to the interface name string. +* @param[in] field_to_parse - Field number to parse from the /proc/net/dev entry. +* +* @return The parsed field value. +* @retval The parsed field value on success. +* @retval 0 if interface not found or error occurs. +* +*/ unsigned long parse_proc_net_dev(char *if_name, int field_to_parse); + +/** +* @brief Get MAC address list from a comma-separated string (utility function). +* +* @param[in] macList - Pointer to the comma-separated MAC address list string. +* @param[out] macAddr - Pointer to the buffer where MAC addresses will be stored. +* @param[in] tok - Delimiter character string. +* @param[out] numlist - Pointer to unsigned long where the count of MAC addresses will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if macList, macAddr, tok, or numlist is NULL. +* +*/ int getMacList(char *macList, unsigned char *macAddr, char *tok, unsigned long *numlist); + +/** +* @brief Set MAC address list to a comma-separated string. +* +* @param[in] macAddr - Pointer to the buffer containing MAC addresses. +* @param[out] macList - Pointer to the buffer where the comma-separated MAC address list will be stored. +* @param[in] numMac - Number of MAC addresses to process. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if macAddr or macList is NULL. +* +*/ int setMacList(unsigned char *macAddr, char *macList, unsigned long numMac); + +/** +* @brief Allocate memory for multi-SSID structure. +* +* @param[in] i - Index for the multi-SSID structure allocation. +* +* @return None. +* +*/ void allocateMultiSSID_Struct(int i); + +/** +* @brief Free memory for multi-SSID structure. +* +* @param[in] i - Index for the multi-SSID structure deallocation. +* +* @return None. +* +*/ void freeMultiSSID_Struct(int i); #endif // __UTAPI_TR_WLAN_H__ diff --git a/source/utapi/lib/utapi_util.h b/source/utapi/lib/utapi_util.h index dc5e398d..4338821a 100644 --- a/source/utapi/lib/utapi_util.h +++ b/source/utapi/lib/utapi_util.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -36,8 +36,8 @@ #ifndef __UTAPI_UTIL_H__ #define __UTAPI_UTIL_H__ -/* - * Generic struct used to map between the various Enums and +/* + * Generic struct used to map between the various Enums and * their syscfg string representations */ typedef struct _EnumString_Map @@ -47,7 +47,7 @@ typedef struct _EnumString_Map } EnumString_Map; /* - * Macros methods with automatic return on error + * Macros methods with automatic return on error * if you don't want automatic return, use the non-macro version */ @@ -238,38 +238,457 @@ typedef struct _EnumString_Map /* * Utility APIs */ +/** +* @brief Convert an enumeration value to its corresponding string representation. +* +* @param[in] pMap - Pointer to an EnumString_Map array for lookup. +* @param[in] iEnum - Enumeration value to convert. +* +* @return Pointer to the string representation of the enumeration. +* @retval Valid string pointer if converted successfully. +* @retval NULL if pMap is NULL or enumeration is not found. +* +*/ char* s_EnumToStr (EnumString_Map* pMap, int iEnum); + +/** +* @brief Convert a string to its corresponding enumeration value. +* +* @param[in] pMap - Pointer to an EnumString_Map array for lookup. +* @param[in] iStr - Pointer to the string to convert. +* +* @return The enumeration value corresponding to the string. +* @retval Valid enumeration value if converted successfully. +* @retval -1 if pMap or iStr is NULL, or if the string is not found. +* +*/ int s_StrToEnum (EnumString_Map* pMap, const char *iStr); +/** +* @brief Validate if a string represents a valid IPv4 address. +* +* @param[in] ip - Pointer to the IP address string to validate. +* +* @return The validation result. +* @retval TRUE if the IP address is valid. +* @retval FALSE if the IP address is invalid or NULL. +* +*/ int IsValid_IPAddr (const char *ip); + +/** +* @brief Validate if an integer represents a valid IPv4 address last octet. +* +* @param[in] ipoctet - Integer value of the last octet to validate. +* \n Valid range: 2 to 254. +* +* @return The validation result. +* @retval TRUE if the octet value is valid (greater than 1 and less than 255). +* @retval FALSE if the octet value is invalid. +* +*/ int IsValid_IPAddrLastOctet (int ipoctet); + +/** +* @brief Validate if a string represents a valid netmask. +* +* @param[in] ip - Pointer to the netmask string to validate. +* +* @return The validation result. +* @retval TRUE if valid. +* +*/ int IsValid_Netmask (const char *ip); + +/** +* @brief Validate if a string represents a valid MAC address. +* +* @param[in] mac - Pointer to the MAC address string to validate. +* +* @return The validation result. +* @retval TRUE if valid +* +*/ int IsValid_MACAddr (const char *mac); + +/** +* @brief Validate if a string represents a valid ULA (Unique Local Address) IPv6 address. +* +* @param[in] address - Pointer to the IPv6 address string to validate. +* \n Format: "address/prefix_length" (e.g., "fc00::/7"). +* \n ULA addresses have the first byte with (byte & 0xfe) == 0xfc. +* +* @return The validation result. +* @retval TRUE if the address is a valid ULA IPv6 address. +* @retval FALSE if the address is invalid, NULL, or not a ULA address. +* +*/ int IsValid_ULAAddress(const char *address); + +/** +* @brief Check if a string contains only integer digits. +* +* @param[in] str - Pointer to the string to check. +* +* @return The validation result. +* @retval TRUE if the string contains only digits. +* @retval FALSE if the string contains non-digit characters. +* +*/ boolean_t IsInteger (const char *str); + +/** +* @brief Check if two IPv4 addresses are on the same network. +* +* @param[in] addr1 - First IPv4 address in network byte order. +* @param[in] addr2 - Second IPv4 address in network byte order. +* @param[in] mask - Network mask in network byte order. +* +* @return The comparison result. +* @retval 1 if addresses are on the same network. +* @retval 0 if addresses are not on the same network. +* +*/ int IsSameNetwork(unsigned long addr1, unsigned long addr2, unsigned long mask); + +/** +* @brief Check if an IPv4 address is a loopback address. +* +* @param[in] addr - IPv4 address in network byte order. +* \n Loopback range: 127.0.0.0/8. +* +* @return The validation result. +* @retval 1 if the address is a loopback address. +* @retval 0 if the address is not a loopback address. +* +*/ int IsLoopback(unsigned long addr); + +/** +* @brief Check if an IPv4 address is a multicast address. +* +* @param[in] addr - IPv4 address in network byte order. +* \n Multicast range: 224.0.0.0/4. +* +* @return The validation result. +* @retval 1 if the address is a multicast address. +* @retval 0 if the address is not a multicast address. +* +*/ int IsMulticast(unsigned long addr); + +/** +* @brief Check if an IPv4 address is a broadcast address. +* +* @param[in] addr - IPv4 address in network byte order. +* @param[in] net - Network address in network byte order. +* @param[in] mask - Network mask in network byte order. +* +* @return The validation result. +* @retval 1 if the address is a broadcast address (all ones, or subnet broadcast). +* @retval 0 if the address is not a broadcast address. +* +*/ int IsBroadcast(unsigned long addr, unsigned long net, unsigned long mask); + +/** +* @brief Check if an IPv4 address is a network address. +* +* @param[in] addr - IPv4 address in network byte order. +* @param[in] net - Network address in network byte order. +* @param[in] mask - Network mask in network byte order. +* +* @return The validation result. +* @retval 1 if the address is a network address (host bits are all zeros). +* @retval 0 if the address is not a network address. +* +*/ int IsNetworkAddr(unsigned long addr, unsigned long net, unsigned long mask); + +/** +* @brief Validate if a netmask is valid (contiguous set bits). +* +* @param[in] netmask - Netmask value in network byte order. +* +* @return The validation result. +* @retval 1 if the netmask has contiguous set bits from left to right. +* @retval 0 if the netmask is invalid. +* +*/ int IsNetmaskValid(unsigned long netmask); + +/** +* @brief Get the MAC address of a network interface. +* +* @param[in] ifname - Pointer to the interface name string. +* @param[out] out_buf - Pointer to the buffer where the MAC address string will be returned. +* \n Format: "xx:xx:xx:xx:xx:xx\n". +* @param[in] bufsz - Size of the output buffer. +* +* @return None. +*/ void s_get_interface_mac (char *ifname, char *out_buf, int bufsz); + +/** +* @brief Connect to the sysevent daemon. +* +* @param[out] out_se_token - Pointer to a token_t where the sysevent token will be returned. +* +* @return The sysevent file descriptor. +* @retval >=0 Valid file descriptor if connection is successful. +* @retval <0 if connection fails. +* +*/ int s_sysevent_connect (token_t *out_se_token); + +/** +* @brief Set an integer value in the Utopia context. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ixUtopia - Utopia value identifier. +* @param[in] value - Integer value to be set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_UTCTX_OP if the Utopia context operation fails. +* +*/ int Utopia_SetInt (UtopiaContext *ctx, UtopiaValue ixUtopia, int value); + +/** +* @brief Set a boolean value in the Utopia context. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ixUtopia - Utopia value identifier. +* @param[in] value - Boolean value to be set (TRUE or FALSE). +* \n TRUE is stored as "1", FALSE as "0". +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_UTCTX_OP if the Utopia context operation fails. +* +*/ int Utopia_SetBool (UtopiaContext *ctx, UtopiaValue ixUtopia, boolean_t value); + +/** +* @brief Set an indexed integer value in the Utopia context. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ixUtopia - Utopia value identifier. +* @param[in] iIndex - Index for the value. +* @param[in] value - Integer value to be set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_UTCTX_OP if the Utopia context operation fails. +* +*/ int Utopia_SetIndexedInt (UtopiaContext *ctx, UtopiaValue ixUtopia, int iIndex, int value); + +/** +* @brief Set an indexed boolean value in the Utopia context. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ixUtopia - Utopia value identifier. +* @param[in] iIndex - Index for the value. +* @param[in] value - Boolean value to be set (TRUE or FALSE). +* \n TRUE is stored as "1", FALSE as "0". +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_UTCTX_OP if the Utopia context operation fails. +* +*/ int Utopia_SetIndexedBool (UtopiaContext *ctx, UtopiaValue ixUtopia, int iIndex, boolean_t value); + +/** +* @brief Set a named integer value in the Utopia context. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ixUtopia - Utopia value identifier. +* @param[in] prefix - Pointer to the name prefix string. +* @param[in] value - Integer value to be set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_UTCTX_OP if the Utopia context operation fails. +* +*/ int Utopia_SetNamedInt (UtopiaContext *ctx, UtopiaValue ixUtopia, char *prefix, int value); + +/** +* @brief Set a named boolean value in the Utopia context. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ixUtopia - Utopia value identifier. +* @param[in] prefix - Pointer to the name prefix string. +* @param[in] value - Boolean value to be set (TRUE or FALSE). +* \n TRUE is stored as "1", FALSE as "0". +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_UTCTX_OP if the Utopia context operation fails. +* +*/ int Utopia_SetNamedBool (UtopiaContext *ctx, UtopiaValue ixUtopia, char *prefix, boolean_t value); + +/** +* @brief Set a named unsigned long value in the Utopia context. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ixUtopia - Utopia value identifier. +* @param[in] prefix - Pointer to the name prefix string. +* @param[in] value - Unsigned long value to be set. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_UTCTX_OP if the Utopia context operation fails. +* +*/ int Utopia_SetNamedLong (UtopiaContext *ctx, UtopiaValue ixUtopia, char *prefix, unsigned long value); + +/** +* @brief Get an integer value from the Utopia context. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ixUtopia - Utopia value identifier. +* @param[out] out_int - Pointer to an integer where the value will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_UTCTX_OP if the Utopia context operation fails. +* @retval ERR_INVALID_INT_VALUE if the retrieved value is not a valid integer. +* +*/ int Utopia_GetInt (UtopiaContext *ctx, UtopiaValue ixUtopia, int *out_int); + +/** +* @brief Get an indexed integer value from the Utopia context. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ixUtopia - Utopia value identifier. +* @param[in] index - Index for the value. +* @param[out] out_int - Pointer to an integer where the value will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_UTCTX_OP if the Utopia context operation fails. +* @retval ERR_INVALID_INT_VALUE if the retrieved value is not a valid integer. +* +*/ int Utopia_GetIndexedInt (UtopiaContext *ctx, UtopiaValue ixUtopia, int index, int *out_int); + +/** +* @brief Get a boolean value from the Utopia context. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ixUtopia - Utopia value identifier. +* @param[out] out_bool - Pointer to a boolean_t where the value will be returned. +* \n "1" is returned as TRUE, all other values as FALSE. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_UTCTX_OP if the Utopia context operation fails. +* +*/ int Utopia_GetBool (UtopiaContext *ctx, UtopiaValue ixUtopia, boolean_t *out_bool); + +/** +* @brief Get an indexed boolean value from the Utopia context. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ixUtopia - Utopia value identifier. +* @param[in] index - Index for the value. +* @param[out] out_bool - Pointer to a boolean_t where the value will be returned. +* \n "1" or "true" is returned as TRUE, all other values as FALSE. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_UTCTX_OP if the Utopia context operation fails. +* +*/ int Utopia_GetIndexedBool (UtopiaContext *ctx, UtopiaValue ixUtopia, int index, boolean_t *out_bool); + +/** +* @brief Get a double-indexed integer value from the Utopia context. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ixUtopia - Utopia value identifier. +* @param[in] index1 - First index for the value. +* @param[in] index2 - Second index for the value. +* @param[out] out_int - Pointer to an integer where the value will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_UTCTX_OP if the Utopia context operation fails. +* @retval ERR_INVALID_INT_VALUE if the retrieved value is not a valid integer. +* +*/ int Utopia_GetIndexed2Int (UtopiaContext *ctx, UtopiaValue ixUtopia, int index1, int index2, int *out_int); + +/** +* @brief Get a double-indexed boolean value from the Utopia context. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ixUtopia - Utopia value identifier. +* @param[in] index1 - First index for the value. +* @param[in] index2 - Second index for the value. +* @param[out] out_bool - Pointer to a boolean_t where the value will be returned. +* \n "1" is returned as TRUE, all other values as FALSE. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_UTCTX_OP if the Utopia context operation fails. +* +*/ int Utopia_GetIndexed2Bool (UtopiaContext *ctx, UtopiaValue ixUtopia, int index1, int index2, boolean_t *out_bool); + +/** +* @brief Get a named boolean value from the Utopia context. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ixUtopia - Utopia value identifier. +* @param[in] name - Pointer to the name string. +* @param[out] out_bool - Pointer to a boolean_t where the value will be returned. +* \n "1" is returned as TRUE, all other values as FALSE. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_UTCTX_OP if the Utopia context operation fails. +* +*/ int Utopia_GetNamedBool (UtopiaContext *ctx, UtopiaValue ixUtopia, char *name, boolean_t *out_bool); + +/** +* @brief Get a named integer value from the Utopia context. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ixUtopia - Utopia value identifier. +* @param[in] name - Pointer to the name string. +* @param[out] out_int - Pointer to an integer where the value will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_UTCTX_OP if the Utopia context operation fails. +* @retval ERR_INVALID_INT_VALUE if the retrieved value is not a valid integer. +* +*/ int Utopia_GetNamedInt (UtopiaContext *ctx, UtopiaValue ixUtopia,char *name, int *out_int); + +/** +* @brief Get a named unsigned long value from the Utopia context. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] ixUtopia - Utopia value identifier. +* @param[in] name - Pointer to the name string. +* @param[out] out_int - Pointer to an unsigned long where the value will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_UTCTX_OP if the Utopia context operation fails. +* @retval ERR_INVALID_INT_VALUE if the retrieved value is not a valid integer. +* +*/ int Utopia_GetNamedLong (UtopiaContext *ctx, UtopiaValue ixUtopia,char *name, unsigned long *out_int); -#endif // __UTAPI_UTIL_H__ +#endif // __UTAPI_UTIL_H__ \ No newline at end of file diff --git a/source/utapi/lib/utapi_wlan.h b/source/utapi/lib/utapi_wlan.h index b6d21290..3f328d03 100644 --- a/source/utapi/lib/utapi_wlan.h +++ b/source/utapi/lib/utapi_wlan.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -38,18 +38,18 @@ #define VERSION 1 #define PASSPHRASE_SZ 64 -#define WEP_KEY_SZ 32 +#define WEP_KEY_SZ 32 #define WEP_KEY_NUM 4 #define SSID_SIZE (4*32+1) -#define STD_CHAN_NUM 20 -#define MAC_ADDR_SIZE 18 +#define STD_CHAN_NUM 20 +#define MAC_ADDR_SIZE 18 #define SHAREDKEY_SZ 64 #define WIFI_INTERFACE_COUNT 2 typedef enum wifiInterface { - FREQ_2_4_GHZ, - FREQ_5_GHZ, + FREQ_2_4_GHZ, + FREQ_5_GHZ, } wifiInterface_t; typedef struct wifiPlatformSetup { @@ -63,12 +63,12 @@ typedef struct wifiPlatformSetup { typedef enum wifiMode { MODE_INVALID = -1, - B_ONLY = 1, - G_ONLY, - A_ONLY, - N_ONLY, - B_G_MIXED, - B_G_N_MIXED, + B_ONLY = 1, + G_ONLY, + A_ONLY, + N_ONLY, + B_G_MIXED, + B_G_N_MIXED, A_N_MIXED, } wifiMode_t; @@ -78,32 +78,32 @@ typedef struct wifi80211Mode { } wifi80211Mode_t; typedef enum { - BAND_INVALID = -1, - BAND_AUTO = 0, - STD_20MHZ, + BAND_INVALID = -1, + BAND_AUTO = 0, + STD_20MHZ, WIDE_40MHZ } wifiBand_t; typedef enum { - SIDEBAND_LOWER, - SIDEBAND_UPPER, + SIDEBAND_LOWER, + SIDEBAND_UPPER, } wifiSideBand_t; typedef enum wifiWideChannel { - WC_AUTO, - WC_1, // for 2.4GHz - WC_2, - WC_3, - WC_4, - WC_5, - WC_6, - WC_7, - WC_36, // for 5GHz - WC_44, - WC_52, - WC_60, - WC_149, + WC_AUTO, + WC_1, // for 2.4GHz + WC_2, + WC_3, + WC_4, + WC_5, + WC_6, + WC_7, + WC_36, // for 5GHz + WC_44, + WC_52, + WC_60, + WC_149, WC_157, } wifiWideChannel_t; @@ -115,29 +115,29 @@ typedef struct wifiWideChannelSetup { #define WIDE_CHAN_NUM 25 typedef enum wifiStdChannel { - SC_AUTO, - SC_1, // for 2.4GHz - SC_2, - SC_3, - SC_4, - SC_5, - SC_6, - SC_7, - SC_8, - SC_9, - SC_10, - SC_11, - SC_36, // for 5GHz + SC_AUTO, + SC_1, // for 2.4GHz + SC_2, + SC_3, + SC_4, + SC_5, + SC_6, + SC_7, + SC_8, + SC_9, + SC_10, + SC_11, + SC_36, // for 5GHz SC_40, - SC_44, - SC_48, - SC_52, - SC_56, - SC_60, - SC_64, - SC_149, - SC_153, - SC_157, + SC_44, + SC_48, + SC_52, + SC_56, + SC_60, + SC_64, + SC_149, + SC_153, + SC_157, SC_161, SC_165, } wifiStdChannel_t; @@ -149,10 +149,10 @@ typedef struct wifiStdChannelSetup { typedef struct wifiRadioInfo { - wifiInterface_t interface; + wifiInterface_t interface; boolean_t enabled; boolean_t ssid_broadcast; - char ssid[SSID_SIZE]; + char ssid[SSID_SIZE]; char mac_address[MAC_ADDR_SIZE+1]; // Only get-able, NA in set operation wifiMode_t mode; wifiBand_t band; @@ -175,11 +175,11 @@ typedef struct wifiRadioInfo { typedef enum wifiSecMode { WIFI_SECURITY_INVALID = -1, WIFI_SECURITY_DISABLED = 0, - WIFI_SECURITY_WEP, - WIFI_SECURITY_WPA_PERSONAL, - WIFI_SECURITY_WPA_ENTERPRISE, - WIFI_SECURITY_WPA2_PERSONAL, - WIFI_SECURITY_WPA2_ENTERPRISE, + WIFI_SECURITY_WEP, + WIFI_SECURITY_WPA_PERSONAL, + WIFI_SECURITY_WPA_ENTERPRISE, + WIFI_SECURITY_WPA2_PERSONAL, + WIFI_SECURITY_WPA2_ENTERPRISE, WIFI_SECURITY_RADIUS, } wifiSecMode_t; @@ -196,10 +196,10 @@ typedef enum WPAEncrypt { } WPAEncrypt_t; typedef struct wifiSecurityInfo { - wifiInterface_t interface; + wifiInterface_t interface; wifiSecMode_t mode; - WPAEncrypt_t encrypt; - char passphrase[PASSPHRASE_SZ]; + WPAEncrypt_t encrypt; + char passphrase[PASSPHRASE_SZ]; int key_renewal_interval; // default 3600secs char wep_key[WEP_KEY_NUM][WEP_KEY_SZ]; int wep_txkey; // valid 1 - 4 @@ -226,8 +226,8 @@ typedef enum wifiAuthType { } wifiAuthType_t; typedef enum wifiBasicRate { - WIFI_BASICRATE_DEFAULT, - WIFI_BASICRATE_1_2MBPS, + WIFI_BASICRATE_DEFAULT, + WIFI_BASICRATE_1_2MBPS, WIFI_BASICRATE_ALL, } wifiBasicRate_t; @@ -235,13 +235,13 @@ typedef enum wifiBasicRate { typedef enum wifiTXRate { WIFI_TX_RATE_AUTO = 0, - WIFI_TX_RATE_6, - WIFI_TX_RATE_9, + WIFI_TX_RATE_6, + WIFI_TX_RATE_9, WIFI_TX_RATE_12, WIFI_TX_RATE_18, - WIFI_TX_RATE_24, - WIFI_TX_RATE_36, - WIFI_TX_RATE_48, + WIFI_TX_RATE_24, + WIFI_TX_RATE_36, + WIFI_TX_RATE_48, WIFI_TX_RATE_54, } wifiTXRate_t; @@ -252,27 +252,27 @@ typedef struct wifiTXRateMapping_t { typedef enum wifiNTXRate { WIFI_N_TX_RATE_AUTO = -1, - WIFI_N_TX_RATE_MSC0_6dot5 = 0, - WIFI_N_TX_RATE_MSC1_13, - WIFI_N_TX_RATE_MSC2_19dot5, - WIFI_N_TX_RATE_MSC3_26, - WIFI_N_TX_RATE_MSC4_39, - WIFI_N_TX_RATE_MSC5_52, - WIFI_N_TX_RATE_MSC6_58dot5, - WIFI_N_TX_RATE_MSC7_65, - WIFI_N_TX_RATE_MSC8_13, - WIFI_N_TX_RATE_MSC9_26, - WIFI_N_TX_RATE_MSC10_39, - WIFI_N_TX_RATE_MSC11_52, - WIFI_N_TX_RATE_MSC12_78, - WIFI_N_TX_RATE_MSC13_104, - WIFI_N_TX_RATE_MSC14_117, - WIFI_N_TX_RATE_MSC15_130, + WIFI_N_TX_RATE_MSC0_6dot5 = 0, + WIFI_N_TX_RATE_MSC1_13, + WIFI_N_TX_RATE_MSC2_19dot5, + WIFI_N_TX_RATE_MSC3_26, + WIFI_N_TX_RATE_MSC4_39, + WIFI_N_TX_RATE_MSC5_52, + WIFI_N_TX_RATE_MSC6_58dot5, + WIFI_N_TX_RATE_MSC7_65, + WIFI_N_TX_RATE_MSC8_13, + WIFI_N_TX_RATE_MSC9_26, + WIFI_N_TX_RATE_MSC10_39, + WIFI_N_TX_RATE_MSC11_52, + WIFI_N_TX_RATE_MSC12_78, + WIFI_N_TX_RATE_MSC13_104, + WIFI_N_TX_RATE_MSC14_117, + WIFI_N_TX_RATE_MSC15_130, } wifiNTXRate_t; typedef enum wifiTXPower { - TX_POWER_HIGH, - TX_POWER_MEDIUM, + TX_POWER_HIGH, + TX_POWER_MEDIUM, TX_POWER_LOW, } wifiTXPower_t; @@ -281,7 +281,7 @@ typedef enum wifiTXPower { #ifndef UTAPI_NO_SEC_MACFILTER typedef struct wifiMacFiltersInfo { - int macFilterMode; + int macFilterMode; int client_count; char client_mac_list[MAX_MACFILTERS][MACADDR_SZ]; } wifiMacFilterInfo_t; @@ -290,45 +290,45 @@ typedef struct wifiMacFiltersInfo { typedef struct wifiAdvancedInfo { - wifiInterface_t interface; - boolean_t ap_isolation; - boolean_t frame_burst; - wifiAuthType_t auth_type; - wifiBasicRate_t basic_rate; - wifiTXRate_t tx_rate; - int n_tx_rate; // MCS index; range 0 to 15 and -1 being auto + wifiInterface_t interface; + boolean_t ap_isolation; + boolean_t frame_burst; + wifiAuthType_t auth_type; + wifiBasicRate_t basic_rate; + wifiTXRate_t tx_rate; + int n_tx_rate; // MCS index; range 0 to 15 and -1 being auto wifiTXPower_t tx_power; - boolean_t auto_cts_protect_mode; - int beacon_interval; // default 100ms; range 1 - 65535 - int dtim_interval; // default 1, range 1 - 255 - int frag_threshold; // default 2346, range 256 - 2346 + boolean_t auto_cts_protect_mode; + int beacon_interval; // default 100ms; range 1 - 65535 + int dtim_interval; // default 1, range 1 - 255 + int frag_threshold; // default 2346, range 256 - 2346 int rts_threshold; // default 2347, range 0 - 2347 } wifiAdvancedInfo_t; typedef struct wifiCounters { - long tx_frames; - long tx_bytes; - long tx_retrans; + long tx_frames; + long tx_bytes; + long tx_retrans; long tx_errors; - long rx_frames; + long rx_frames; long rx_bytes; long rx_errors; } wifiCounters_t; typedef struct wifiStatusInfo { - char mac_addr[MAC_ADDR_SIZE+1]; - char radio_mode[16]; // wifiMode - char ssid[SSID_SIZE]; - int channel; - char security[32]; - int ssid_broadcast; // 1=enabled, 0=disabled + char mac_addr[MAC_ADDR_SIZE+1]; + char radio_mode[16]; // wifiMode + char ssid[SSID_SIZE]; + int channel; + char security[32]; + int ssid_broadcast; // 1=enabled, 0=disabled wifiCounters_t counters; } wifiStatusInfo_t; -typedef struct wifiQoS { - boolean_t wmm_support; +typedef struct wifiQoS { + boolean_t wmm_support; boolean_t no_acknowledgement; -} wifiQoS_t; +} wifiQoS_t; typedef enum wifiConfigMode { WIFI_CONFIG_MANUAL, @@ -358,33 +358,282 @@ typedef struct wifiBridgeInfo { /* * APIs - */ + */ +/** +* @brief Set the WiFi radio state (enable/disable). +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] intf - WiFi interface identifier. +* @param[in] enable - Boolean value to enable or disable the radio. +* \n TRUE sets the radio state to "up", FALSE sets it to "down". +* \n Triggers WLAN_Restart event. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx is NULL or intf is >= WIFI_INTERFACE_COUNT. +* +*/ int Utopia_SetWifiRadioState (UtopiaContext *ctx, wifiInterface_t intf, boolean_t enable); + +/** +* @brief Get the WiFi radio state (enabled/disabled). +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] intf - WiFi interface identifier. +* @param[out] enable - Pointer to a boolean_t where the radio state will be returned. +* \n TRUE if radio state is "up", FALSE otherwise. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx, enable is NULL, or intf is >= WIFI_INTERFACE_COUNT. +* @retval ERR_ITEM_NOT_FOUND if the radio state cannot be retrieved from syscfg. +* +*/ int Utopia_GetWifiRadioState (UtopiaContext *ctx, wifiInterface_t intf, boolean_t *enable); +/** +* @brief Get the WiFi radio parameters. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] intf - WiFi interface identifier. +* @param[out] info - Pointer to a wifiRadioInfo_t structure where the radio settings will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx, info is NULL, or intf is >= WIFI_INTERFACE_COUNT. +* @retval ERR_ITEM_NOT_FOUND if required configuration values cannot be retrieved from syscfg. +* @retval ERR_WIFI_INVALID_MODE if the network mode or radio band value is invalid. +* +*/ int Utopia_GetWifiRadioSettings (UtopiaContext *ctx, wifiInterface_t intf, wifiRadioInfo_t *info); + +/** +* @brief Set the WiFi radio parameters. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] info - Pointer to a wifiRadioInfo_t structure containing the radio settings to be set. +* \n Triggers WLAN_Restart event. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx, info is NULL, or interface is >= WIFI_INTERFACE_COUNT. +* @retval ERR_INVALID_VALUE if the mode or band values cannot be converted to strings. +* +*/ int Utopia_SetWifiRadioSettings (UtopiaContext *ctx, wifiRadioInfo_t *info); #ifndef UTAPI_NO_SEC_MACFILTER -int Utopia_GetWifiSecuritySettings (UtopiaContext *ctx, wifiInterface_t intf, wifiSecurityInfo_t *info); +/** +* @brief Get the WiFi security parameters. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] intf - WiFi interface identifier. +* @param[out] info - Pointer to a wifiSecurityInfo_t structure where the security settings will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx, info is NULL, or intf is >= WIFI_INTERFACE_COUNT. +* @retval ERR_ITEM_NOT_FOUND if the security mode cannot be retrieved from syscfg. +* @retval ERR_INVALID_VALUE if the security mode or encryption type is invalid. +* +*/ +int Utopia_GetWifiSecuritySettings (UtopiaContext *ctx, wifiInterface_t intf, wifiSecurityInfo_t *info); + +/** +* @brief Set the WiFi security parameters. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] info - Pointer to a wifiSecurityInfo_t structure containing the security settings to be set. +* \n Triggers WLAN_Restart event. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx, info is NULL, or interface is >= WIFI_INTERFACE_COUNT. +* @retval ERR_INVALID_VALUE if the security mode cannot be converted to a string. +* +*/ int Utopia_SetWifiSecuritySettings (UtopiaContext *ctx, wifiSecurityInfo_t *info); + +/** +* @brief Get the WiFi MAC filter settings. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] info - Pointer to a wifiMacFilterInfo_t structure where the MAC filter settings will be returned. +* \n Maximum MAC filters: 32. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or info is NULL. +* @retval ERR_INVALID_VALUE if the MAC filter mode value is invalid. +* +*/ int Utopia_GetWifiMacFilters (UtopiaContext *ctx, wifiMacFilterInfo_t *info); + +/** +* @brief Set the WiFi MAC filter settings. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] info - Pointer to a wifiMacFilterInfo_t structure containing the MAC filter settings to be set. +* \n Triggers WLAN_Restart event. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or info is NULL. +* @retval ERR_INVALID_VALUE if the MAC filter mode cannot be converted to a string. +* +*/ int Utopia_SetWifiMacFilters (UtopiaContext *ctx, wifiMacFilterInfo_t *info); #endif + +/** +* @brief Get the WiFi advanced settings. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] intf - WiFi interface identifier. +* @param[out] info - Pointer to a wifiAdvancedInfo_t structure where the advanced settings will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx, info is NULL, or intf is >= WIFI_INTERFACE_COUNT. +* +*/ int Utopia_GetWifiAdvancedSettings (UtopiaContext *ctx, wifiInterface_t intf, wifiAdvancedInfo_t *info); + +/** +* @brief Set the WiFi advanced settings. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] info - Pointer to a wifiAdvancedInfo_t structure containing the advanced settings to be set. +* \n Triggers WLAN_Restart event. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx, info is NULL, or interface is >= WIFI_INTERFACE_COUNT. +* +*/ int Utopia_SetWifiAdvancedSettings (UtopiaContext *ctx, wifiAdvancedInfo_t *info); +/** +* @brief Set the WiFi Quality of Service (QoS) settings. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] wifiqos - Pointer to a wifiQoS_t structure containing the QoS settings to be set. +* \n Triggers WLAN_Restart event. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* +*/ int Utopia_SetWifiQoSSettings (UtopiaContext *ctx, wifiQoS_t *wifiqos); + +/** +* @brief Get the WiFi Quality of Service (QoS) settings. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] wifiqos - Pointer to a wifiQoS_t structure where the QoS settings will be returned. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* +*/ int Utopia_GetWifiQoSSettings (UtopiaContext *ctx, wifiQoS_t *wifiqos); +/** +* @brief Get the WiFi configuration mode. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] config_mode - Pointer to a wifiConfigMode_t where the configuration mode will be returned. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or config_mode is NULL. +* @retval ERR_WIFI_INVALID_CONFIG_MODE if the configuration mode value is invalid. +* +*/ int Utopia_GetWifiConfigMode (UtopiaContext *ctx, wifiConfigMode_t *config_mode); + +/** +* @brief Set the WiFi configuration mode. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] config_mode - WiFi configuration mode to be set. +* \n Triggers WLAN_Restart event. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx is NULL. +* @retval ERR_WIFI_INVALID_CONFIG_MODE if the configuration mode value is invalid. +* +*/ int Utopia_SetWifiConfigMode (UtopiaContext *ctx, wifiConfigMode_t config_mode); +/** +* @brief Start WPS (Wi-Fi Protected Setup) using Push Button Configuration (PBC) method. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_WPSPushButtonStart (void); + +/** +* @brief Start WPS (Wi-Fi Protected Setup) using PIN method. +* +* @param[in] pin - WPS PIN code to use for authentication. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_WPSPinStart (int pin); + +/** +* @brief Stop WPS (Wi-Fi Protected Setup) operation. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* +*/ int Utopia_WPSStop (void); + +/** +* @brief Get the current WPS (Wi-Fi Protected Setup) status. +* +* @param[out] wps_status - Pointer to a wpsStatus_t where the WPS status will be returned. +* +* @return The status of the operation. +* @retval SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if wps_status is NULL. +* @retval ERR_FILE_NOT_FOUND if the WPS status command cannot be executed. +* @retval ERR_INVALID_VALUE if the WPS status string cannot be read or is empty. +* +*/ int Utopia_GetWPSStatus (wpsStatus_t *wps_status); +/** +* @brief Get the WiFi bridge settings. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[out] info - Pointer to a wifiBridgeInfo_t structure where the bridge settings will be returned. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or info is NULL. +* +*/ int Utopia_GetWifiBridgeSettings (UtopiaContext *ctx, wifiBridgeInfo_t *info); + +/** +* @brief Set the WiFi bridge settings. +* +* @param[in] ctx - Pointer to the Utopia context. +* @param[in] info - Pointer to a wifiBridgeInfo_t structure containing the bridge settings to be set. +* \n Triggers WLAN_Restart event. +* +* @return The status of the operation. +* @retval UT_SUCCESS if the operation is successful. +* @retval ERR_INVALID_ARGS if ctx or info is NULL. +* +*/ int Utopia_SetWifiBridgeSettings (UtopiaContext *ctx, wifiBridgeInfo_t *info); #endif // __UTAPI_WLAN_H__ diff --git a/source/utctx/lib/utctx.h b/source/utctx/lib/utctx.h index 7d3928e6..9738262e 100644 --- a/source/utctx/lib/utctx.h +++ b/source/utctx/lib/utctx.h @@ -63,24 +63,42 @@ typedef struct _UtopiaContext UtopiaRWLock rwLock; } UtopiaContext; -/* - * Procedure : Utopia_Init - * Purpose : Initialize Utopia context - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Initialize Utopia context for configuration management. +* +* This function initializes a UtopiaContext structure by setting up the transaction list, +* clearing event flags, initializing the sysevent handle, and initializing both the UtopiaRWLock +* and syscfg subsystems. +* +* @param[in,out] pUtopiaCtx - Pointer to the UtopiaContext structure to initialize. +* \n The structure should be allocated by the caller. +* \n On success, all fields are initialized to their default states. +* +* @return The status of the operation. +* @retval 1 if the context was successfully initialized. +* @retval 0 if the operation failed. +* +*/ extern int Utopia_Init(UtopiaContext* pUtopiaCtx); -/* - * Procedure : Utopia_Free - * Purpose : Commit all values stored in the transaction if fCommit is true, free up context memory - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * fCommit - Commit transaction is true - * Return Values : - */ +/** +* @brief Commit transaction values and free Utopia context resources. +* +* This function finalizes all configuration operations by optionally committing all pending +* transaction values to persistent storage, triggering registered system events, and freeing all allocated resources. If fCommit is false, +* free up context memory. The function releases the UtopiaRWLock, closes sysevent handles, +* and frees the transaction list. +* +* @param[in,out] pUtopiaCtx - Pointer to the UtopiaContext structure to free. +* \n All pending transactions will be committed or discarded based on fCommit. +* \n All allocated resources will be released. +* @param[in] fCommit - Boolean flag indicating whether to commit pending changes. +* \n Pass non-zero (true) to commit all transactions and trigger events. +* \n Pass 0 (false) to free up context memory without committing. +* +* @return None. +* +*/ extern void Utopia_Free(UtopiaContext* pUtopiaCtx, int fCommit); #endif /* __UTCTX_H__ */ diff --git a/source/utctx/lib/utctx_api.h b/source/utctx/lib/utctx_api.h index 4eeff94d..d91abb62 100644 --- a/source/utctx/lib/utctx_api.h +++ b/source/utctx/lib/utctx_api.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -50,7 +50,7 @@ #define UTOPIA_MAX_PASSWD_LENGTH 64 #define UTOPIA_MIN_PASSWD_LENGTH 1 #define UTOPIA_MAX_USERNAME_LENGTH 63 -#define UTOPIA_DEFAULT_ADMIN_PASSWD "admin" +#define UTOPIA_DEFAULT_ADMIN_PASSWD "admin" #define UTOPIA_DEFAULT_ADMIN_USER "admin" /* @@ -147,7 +147,7 @@ typedef enum _UtopiaValue UtopiaValue_Mgmt_WANIPrange_SrcEndIP, UtopiaValue_Mgmt_WANIPRange_SrcStartIP, UtopiaValue_Mgmt_WANIPrange_Desp, - UtopiaValue_Mgmt_WANIPrange_InsNum, + UtopiaValue_Mgmt_WANIPrange_InsNum, UtopiaValue_Mgmt_IGDEnabled, UtopiaValue_Mgmt_IGDUserConfig, UtopiaValue_Mgmt_IGDWANDisable, @@ -603,8 +603,8 @@ typedef enum _UtopiaValue UtopiaValue_USGv2_Lan_Clients_Count, UtopiaValue_USGv2_Lan_Clients, UtopiaValue_USGv2_Lan_Clients_Mac, - UtopiaValue_PNM_Status, - UtopiaValue_SPF_PrevRuleEnabledState, + UtopiaValue_PNM_Status, + UtopiaValue_SPF_PrevRuleEnabledState, UtopiaValue_PFR_PrevRuleEnabledState, UtopiaValue_PRT_PrevRuleEnabledState, UtopiaValue_HashPassword, @@ -635,325 +635,452 @@ typedef enum _UtopiaValue UtopiaValue__LAST__ } UtopiaValue; -/* - * Procedure : Utopia_GetKey - * Purpose : Retrieve a Utopia key - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * pszBuffer - Buffer to store output key string - * ccbBuf - Output buffer size - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Retrieve a Utopia key string for a given UtopiaValue index. +* +* This function retrieves the key string associated with a UtopiaValue index. +* +* @param[in] pUtopiaCtx - Pointer to the UtopiaContext containing the system state. +* @param[in] ixUtopia - UtopiaValue enumeration index specifying which key to retrieve. +* @param[out] pszBuffer - Pointer to a buffer where the key string will be stored. +* \n Must be allocated by the caller. +* @param[in] ccbBuf - Size of the output buffer in bytes. +* +* @return The status of the operation. +* @retval 1 if the key was successfully retrieved. +* @retval 0 if the operation failed. +* +*/ extern int Utopia_GetKey(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, char* pszBuffer, unsigned int ccbBuf); -/* - * Procedure : Utopia_GetIndexedKey - * Purpose : Retrieve a Utopia value with a key that is numerically indexed - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * iIndex - The numeric index of the key - * pszBuffer - Buffer to store output key string - * ccbBuf - Output buffer size - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Retrieve a Utopia key string with a numerically indexed key. +* +* This function retrieves the key string for a UtopiaValue that uses numeric indexing. +* +* @param[in] pUtopiaCtx - Pointer to the UtopiaContext containing the system state. +* @param[in] ixUtopia - UtopiaValue enumeration index specifying the base key. +* @param[in] iIndex - The numeric index to append to the key. +* @param[out] pszBuffer - Pointer to a buffer where the indexed key string will be stored. +* \n Must be allocated by the caller. +* @param[in] ccbBuf - Size of the output buffer in bytes. +* +* @return The status of the operation. +* @retval 1 if the indexed key was successfully retrieved. +* @retval 0 if the operation failed. +* +*/ extern int Utopia_GetIndexedKey(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, int iIndex, char* pszBuffer, unsigned int ccbBuf); -/* - * Procedure : Utopia_GetIndexed2Key - * Purpose : Retrieve a Utopia value with a key that is two-dimensionally indexed - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * iIndex1 - The numeric index 1 - * iIndex2 - The numeric index 2 - * pszBuffer - Buffer to store output key string - * ccbBuf - Output buffer size - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Retrieve a Utopia key string with a two-dimensionally indexed key. +* +* This function retrieves the key string for a UtopiaValue that uses two-dimensional numeric indexing. +* +* @param[in] pUtopiaCtx - Pointer to the UtopiaContext containing the system state. +* @param[in] ixUtopia - UtopiaValue enumeration index specifying the base key. +* @param[in] iIndex1 - The first numeric index dimension. +* @param[in] iIndex2 - The second numeric index dimension. +* @param[out] pszBuffer - Pointer to a buffer where the indexed key string will be stored. +* \n Must be allocated by the caller. +* @param[in] ccbBuf - Size of the output buffer in bytes. +* +* @return The status of the operation. +* @retval 1 if the two-dimensionally indexed key was successfully retrieved. +* @retval 0 if the operation failed. +* +*/ extern int Utopia_GetIndexed2Key(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, int iIndex1, int iIndex2, char* pszBuffer, unsigned int ccbBuf); -/* - * Procedure : Utopia_GetNamedKey - * Purpose : Retrieve a Utopia key that is indexed with a string - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * pszName - Index string - * pszBuffer - Buffer to store output key string - * ccbBuf - Output buffer size - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Retrieve a Utopia key string that is indexed with a string name. +* +* This function retrieves the key string for a UtopiaValue that uses string-based indexing. +* +* @param[in] pUtopiaCtx - Pointer to the UtopiaContext containing the system state. +* @param[in] ixUtopia - UtopiaValue enumeration index specifying the base key. +* @param[in] pszName - Null-terminated string used as the name index. +* @param[out] pszBuffer - Pointer to a buffer where the named key string will be stored. +* \n Must be allocated by the caller. +* @param[in] ccbBuf - Size of the output buffer in bytes. +* +* @return The status of the operation. +* @retval 1 if the named key was successfully retrieved. +* @retval 0 if the operation failed. +* +*/ extern int Utopia_GetNamedKey(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, char* pszName, char* pszBuffer, unsigned int ccbBuf); -/* - * Procedure : Utopia_GetNamed2Key - * Purpose : Retrieve Utopia key that is two-dimensionally indexed by strings - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * pszName1 - Index string 1 - * pszName2 - Index string 2 - * pszBuffer - Buffer to store output key string - * ccbBuf - Output buffer size - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Retrieve Utopia key that is two-dimensionally indexed by string names. +* +* This function retrieves the key string for a UtopiaValue that uses two-dimensional string-based indexing. +* +* @param[in] pUtopiaCtx - Pointer to the UtopiaContext containing the system state. +* @param[in] ixUtopia - UtopiaValue enumeration index specifying the base key. +* @param[in] pszName1 - Null-terminated string for the first name index dimension. +* @param[in] pszName2 - Null-terminated string for the second name index dimension. +* @param[out] pszBuffer - Pointer to a buffer where the two-dimensionally named key string will be stored. +* \n Must be allocated by the caller. +* @param[in] ccbBuf - Size of the output buffer in bytes. +* +* @return The status of the operation. +* @retval 1 if the two-dimensionally named key was successfully retrieved. +* @retval 0 if the operation failed. +* +*/ extern int Utopia_GetNamed2Key(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, char* pszName1, char* pszName2, char* pszBuffer, unsigned int ccbBuf); -/* - * Procedure : Utopia_Get - * Purpose : Retrieve a Utopia value - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * pszBuffer - Buffer to store output value string - * ccbBuf - Output buffer size - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Retrieve a Utopia value for a given UtopiaValue index. +* +* This function retrieves the value associated with a UtopiaValue index from either the configuration system, +* event system, or static value table depending on the UtopiaValue type. +* +* @param[in] pUtopiaCtx - Pointer to the UtopiaContext containing the system state. +* @param[in] ixUtopia - UtopiaValue enumeration index specifying which value to retrieve. +* @param[out] pszBuffer - Pointer to a buffer where the value string will be stored. +* \n Must be allocated by the caller. +* @param[in] ccbBuf - Size of the output buffer in bytes. +* +* @return The status of the operation. +* @retval 1 if the value was successfully retrieved. +* @retval 0 if the operation failed. +* +*/ extern int Utopia_Get(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, char* pszBuffer, unsigned int ccbBuf); -/* - * Procedure : Utopia_GetAll - * Purpose : Returns all set values in the format '::=\n' - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * pszBuffer - Null-terminated return buffer - * ccbBuf - Size of the passed in return buffer - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Returns all set Utopia values in a formatted string. +* +* This function retrieves all currently set configuration and event values from the Utopia system +* and returns them in a formatted string with the format '::=\n' for each entry. + +* +* @param[in] pUtopiaCtx - Pointer to the UtopiaContext containing the system state. +* @param[out] pszBuffer - Pointer to a null-terminated buffer where all values will be stored in the format +* \n '::=\n' for each entry. +* \n Must be allocated by the caller with sufficient size. +* @param[in] ccbBuf - Size of the output buffer in bytes. +* \n Should be at least UTOPIA_STATE_SIZE (32KB) for complete retrieval. +* +* @return The status of the operation. +* @retval 1 if all values were successfully retrieved. +* @retval 0 if the operation failed. +* +*/ extern int Utopia_GetAll(UtopiaContext* pUtopiaCtx, char* pszBuffer, unsigned int ccbBuf); -/* - * Procedure : Utopia_GetIndexed - * Purpose : Retrieve a Utopia value with a key that is numerically indexed - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * iIndex - The numeric index of the key - * pszBuffer - Buffer to store output value string - * ccbBuf - Output buffer size - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Retrieve a Utopia value with a numerically indexed key. +* +* This function retrieves the value for a UtopiaValue that uses numeric indexing from the configuration system. +* +* @param[in] pUtopiaCtx - Pointer to the UtopiaContext containing the system state. +* @param[in] ixUtopia - UtopiaValue enumeration index specifying the base key. +* @param[in] iIndex - The numeric index to identify the specific value. +* @param[out] pszBuffer - Pointer to a buffer where the indexed value string will be stored. +* \n Must be allocated by the caller. +* @param[in] ccbBuf - Size of the output buffer in bytes. +* +* @return The status of the operation. +* @retval 1 if the indexed value was successfully retrieved. +* @retval 0 if the operation failed. +* +*/ extern int Utopia_GetIndexed(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, int iIndex, char* pszBuffer, unsigned int ccbBuf); -/* - * Procedure : Utopia_GetIndexed2 - * Purpose : Retrieve a Utopia value with a key that is two-dimensionally indexed - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * iIndex1 - The numeric index 1 - * iIndex2 - The numeric index 2 - * pszBuffer - Buffer to store output value string - * ccbBuf - Output buffer size - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Retrieve a Utopia value with a two-dimensionally indexed key. +* +* This function retrieves the value for a UtopiaValue that uses two-dimensional numeric indexing +* from the configuration system. +* +* @param[in] pUtopiaCtx - Pointer to the UtopiaContext containing the system state. +* @param[in] ixUtopia - UtopiaValue enumeration index specifying the base key. +* @param[in] iIndex1 - The first numeric index dimension. +* @param[in] iIndex2 - The second numeric index dimension. +* @param[out] pszBuffer - Pointer to a buffer where the two-dimensionally indexed value string will be stored. +* \n Must be allocated by the caller. +* @param[in] ccbBuf - Size of the output buffer in bytes. +* +* @return The status of the operation. +* @retval 1 if the two-dimensionally indexed value was successfully retrieved. +* @retval 0 if the operation failed. +* +*/ extern int Utopia_GetIndexed2(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, int iIndex1, int iIndex2, char* pszBuffer, unsigned int ccbBuf); -/* - * Procedure : Utopia_GetNamed - * Purpose : Retrieve a Utopia value with a key that is indexed with a string - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * pszName - Index string - * pszBuffer - Buffer to store output value string - * ccbBuf - Output buffer size - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Retrieve a Utopia value with a key that is indexed with a string name. +* +* This function retrieves the value for a UtopiaValue that uses string-based indexing from the +* configuration system. +* +* @param[in] pUtopiaCtx - Pointer to the UtopiaContext containing the system state. +* @param[in] ixUtopia - UtopiaValue enumeration index specifying the base key. +* @param[in] pszName - Null-terminated string used as the name index. +* @param[out] pszBuffer - Pointer to a buffer where the named value string will be stored. +* \n Must be allocated by the caller. +* @param[in] ccbBuf - Size of the output buffer in bytes. +* +* @return The status of the operation. +* @retval 1 if the named value was successfully retrieved. +* @retval 0 if the operation failed. +* +*/ extern int Utopia_GetNamed(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, char* pszName, char* pszBuffer, unsigned int ccbBuf); -/* - * Procedure : Utopia_GetNamed2 - * Purpose : Retrieve a Utopia value with a key that is two-dimensionally indexed by strings - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * pszName1 - Index string 1 - * pszName2 - Index string 2 - * pszBuffer - Buffer to store output value string - * ccbBuf - Output buffer size - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Retrieve a Utopia value with a key that is two-dimensionally indexed by string names. +* +* This function retrieves the value for a UtopiaValue that uses two-dimensional string-based indexing +* from the configuration system. +* +* @param[in] pUtopiaCtx - Pointer to the UtopiaContext containing the system state. +* @param[in] ixUtopia - UtopiaValue enumeration index specifying the base key. +* @param[in] pszName1 - Null-terminated string for the first name index dimension. +* @param[in] pszName2 - Null-terminated string for the second name index dimension. +* @param[out] pszBuffer - Pointer to a buffer where the two-dimensionally named value string will be stored. +* \n Must be allocated by the caller. +* @param[in] ccbBuf - Size of the output buffer in bytes. +* +* @return The status of the operation. +* @retval 1 if the two-dimensionally named value was successfully retrieved. +* @retval 0 if the operation failed. +* +*/ extern int Utopia_GetNamed2(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, char* pszName1, char* pszName2, char* pszBuffer, unsigned int ccbBuf); -/* - * Procedure : Utopia_RawGet - * Purpose : Retrieve a raw non-Utopia value (UtopiaValue doesn't exist) - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * pszNamespace - Namespace of the value retrieved - * pszKey - Key of the value being retrieved - * pszBuffer - Buffer to store output value string - * ccbBuf - Output buffer size - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Retrieve a raw non-Utopia value directly by namespace and key. +* +* This function retrieves a value directly from the underlying configuration system using explicit +* namespace and key parameters, bypassing the UtopiaValue enumeration. +* +* @param[in] pUtopiaCtx - Pointer to the UtopiaContext containing the system state. +* @param[in] pszNamespace - Null-terminated string specifying the namespace of the value to retrieve. +* @param[in] pszKey - Null-terminated string specifying the key of the value being retrieved. +* @param[out] pszBuffer - Pointer to a buffer where the value string will be stored. +* \n Must be allocated by the caller. +* @param[in] ccbBuf - Size of the output buffer in bytes. +* +* @return The status of the operation. +* @retval 1 if the raw value was successfully retrieved. +* @retval 0 if the operation failed. +* +*/ extern int Utopia_RawGet(UtopiaContext* pUtopiaCtx, char* pszNamespace, char* pszKey, char* pszBuffer, unsigned int ccbBuf); -/* - * Procedure : Utopia_RawSet - * Purpose : Set a raw non-Utopia value (UtopiaValue doesn't exist) - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * pszNamespace - Namespace of value being set - * pszKey - Key of value being set - * pszValue - Value being set - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Set a raw non-Utopia value directly by namespace and key. +* +* This function sets a value directly in the underlying configuration system using explicit +* namespace and key parameters, bypassing the UtopiaValue enumeration. +* +* @param[in] pUtopiaCtx - Pointer to the UtopiaContext containing the system state. +* @param[in] pszNamespace - Null-terminated string specifying the namespace of the value being set. +* @param[in] pszKey - Null-terminated string specifying the key of the value being set. +* @param[in] pszValue - Null-terminated string containing the value to set. +* +* @return The status of the operation. +* @retval 1 if the raw value was successfully set. +* @retval 0 if the operation failed. +* +*/ extern int Utopia_RawSet(UtopiaContext* pUtopiaCtx, char* pszNamespace, char* pszKey, char* pszValue); -/* - * Procedure : Utopia_Set - * Purpose : Set a Utopia value - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * pszValue - Value being set - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Set a Utopia value for a given UtopiaValue index. +* +* This function sets the value associated with a UtopiaValue index in the configuration or event system. +* +* @param[in] pUtopiaCtx - Pointer to the UtopiaContext containing the system state. +* @param[in] ixUtopia - UtopiaValue enumeration index specifying which value to set. +* @param[in] pszValue - Null-terminated string containing the value to set. +* +* @return The status of the operation. +* @retval 1 if the value was successfully set. +* @retval 0 if the operation failed. +* +*/ extern int Utopia_Set(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, char* pszValue); -/* - * Procedure : Utopia_SetAll - * Purpose : Sets all of the values in the input buffer, which should be formatted '::=\n'. - * : Passing in a null buffer will result in all values being set to factory defaults. - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * pszBuffer - Null-terminated input buffer - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Sets all Utopia values from a formatted input buffer or resets to factory defaults. +* +* This function sets all configuration and event values in the Utopia system from a formatted input buffer +* with the format '::=\n' for each entry. If a null buffer is passed, all values +* are reset to factory defaults. +* +* @param[in] pUtopiaCtx - Pointer to the UtopiaContext containing the system state. +* @param[in] pszBuffer - Pointer to a null-terminated input buffer containing values in the format +* \n '::=\n' for each entry. +* \n Pass NULL to reset all values to factory defaults. +* +* @return The status of the operation. +* @retval 1 if all values were successfully set or reset. +* @retval 0 if the operation failed. +* +*/ extern int Utopia_SetAll(UtopiaContext* pUtopiaCtx, char* pszBuffer); -/* - * Procedure : Utopia_SetIndexed - * Purpose : Set a Utopia value with a key that is numerically indexed - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * pszValue - Value being set - * iIndex - The numeric index - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Set a Utopia value with a numerically indexed key. +* +* This function sets the value for a UtopiaValue that uses numeric indexing in the configuration system. +* +* @param[in] pUtopiaCtx - Pointer to the UtopiaContext containing the system state. +* @param[in] ixUtopia - UtopiaValue enumeration index specifying the base key. +* @param[in] iIndex - The numeric index to identify the specific value. +* @param[in] pszValue - Null-terminated string containing the value to set. +* +* @return The status of the operation. +* @retval 1 if the indexed value was successfully set. +* @retval 0 if the operation failed. +* +*/ extern int Utopia_SetIndexed(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, int iIndex, char* pszValue); -/* - * Procedure : Utopia_SetIndexed2 - * Purpose : Set a Utopia value with a key that is two-dimensionally indexed - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * iIndex1 - The numeric index 1 - * iIndex2 - The numeric index 2 - * pszValue - Value being set - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Set a Utopia value with a two-dimensionally indexed key. +* +* This function sets the value for a UtopiaValue that uses two-dimensional numeric indexing in the +* configuration system. +* +* @param[in] pUtopiaCtx - Pointer to the UtopiaContext containing the system state. +* @param[in] ixUtopia - UtopiaValue enumeration index specifying the base key. +* @param[in] iIndex1 - The first numeric index dimension. +* @param[in] iIndex2 - The second numeric index dimension. +* @param[in] pszValue - Null-terminated string containing the value to set. +* +* @return The status of the operation. +* @retval 1 if the two-dimensionally indexed value was successfully set. +* @retval 0 if the operation failed. +* +*/ extern int Utopia_SetIndexed2(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, int iIndex1, int iIndex2, char* pszValue); -/* - * Procedure : Utopia_SetNamed - * Purpose : Set a Utopia value with a key that is indexed with a string - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * pszName - Index string - * pszValue - Value being set - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Set a Utopia value with a key that is indexed with a string name. +* +* This function sets the value for a UtopiaValue that uses string-based indexing in the configuration system. +* +* @param[in] pUtopiaCtx - Pointer to the UtopiaContext containing the system state. +* @param[in] ixUtopia - UtopiaValue enumeration index specifying the base key. +* @param[in] pszName - Null-terminated string used as the name index. +* @param[in] pszValue - Null-terminated string containing the value to set. +* +* @return The status of the operation. +* @retval 1 if the named value was successfully set. +* @retval 0 if the operation failed. +* +*/ extern int Utopia_SetNamed(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, char* pszName, char* pszValue); -/* - * Procedure : Utopia_SetNamed2 - * Purpose : Set a Utopia value with a key that is two-dimensionally indexed by strings - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * pszName1 - Index string 1 - * pszName2 - Index string 2 - * pszValue - Value being set - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Set a Utopia value with a key that is two-dimensionally indexed by string names. +* +* This function sets the value for a UtopiaValue that uses two-dimensional string-based indexing in the +* configuration system. +* +* @param[in] pUtopiaCtx - Pointer to the UtopiaContext containing the system state. +* @param[in] ixUtopia - UtopiaValue enumeration index specifying the base key. +* @param[in] pszName1 - Null-terminated string for the first name index dimension. +* @param[in] pszName2 - Null-terminated string for the second name index dimension. +* @param[in] pszValue - Null-terminated string containing the value to set. +* +* @return The status of the operation. +* @retval 1 if the two-dimensionally named value was successfully set. +* @retval 0 if the operation failed. +* +*/ extern int Utopia_SetNamed2(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, char* pszName1, char* pszName2, char* pszValue); -/* - * Procedure : Utopia_Unset - * Purpose : Unset a Utopia value - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * pszValue - Value being set - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Unset a Utopia value for a given UtopiaValue index. +* +* This function removes/clears the value associated with a UtopiaValue index from the configuration or +* event system. +* +* @param[in] pUtopiaCtx - Pointer to the UtopiaContext containing the system state. +* @param[in] ixUtopia - UtopiaValue enumeration index specifying which value to unset. +* +* @return The status of the operation. +* @retval 1 if the value was successfully unset. +* @retval 0 if the operation failed. +* +*/ extern int Utopia_Unset(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia); -/* - * Procedure : Utopia_UnsetIndexed - * Purpose : Unset a Utopia value with a key that is numerically indexed - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * iIndex - The numeric index - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Unset a Utopia value with a numerically indexed key. +* +* This function removes/clears the value for a UtopiaValue that uses numeric indexing from the +* configuration system. +* +* @param[in] pUtopiaCtx - Pointer to the UtopiaContext containing the system state. +* @param[in] ixUtopia - UtopiaValue enumeration index specifying the base key. +* @param[in] iIndex - The numeric index to identify the specific value to unset. +* +* @return The status of the operation. +* @retval 1 if the indexed value was successfully unset. +* @retval 0 if the operation failed. +* +*/ extern int Utopia_UnsetIndexed(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, int iIndex); -/* - * Procedure : Utopia_UnsetIndexed2 - * Purpose : Unset a Utopia value with a key that is two-dimensionally indexed - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * iIndex1 - The numeric index 1 - * iIndex2 - The numeric index 2 - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Unset a Utopia value with a two-dimensionally indexed key. +* +* This function removes/clears the value for a UtopiaValue that uses two-dimensional numeric indexing +* from the configuration system. +* +* @param[in] pUtopiaCtx - Pointer to the UtopiaContext containing the system state. +* @param[in] ixUtopia - UtopiaValue enumeration index specifying the base key. +* @param[in] iIndex1 - The first numeric index dimension. +* @param[in] iIndex2 - The second numeric index dimension. +* +* @return The status of the operation. +* @retval 1 if the two-dimensionally indexed value was successfully unset. +* @retval 0 if the operation failed. +* +*/ extern int Utopia_UnsetIndexed2(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, int iIndex1, int iIndex2); -/* - * Procedure : Utopia_UnsetNamed - * Purpose : Unset a Utopia value with a key that is indexed with a string - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * pszName - Index string - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Unset a Utopia value with a key that is indexed with a string name. +* +* This function removes/clears the value for a UtopiaValue that uses string-based indexing from the +* configuration system. +* +* @param[in] pUtopiaCtx - Pointer to the UtopiaContext containing the system state. +* @param[in] ixUtopia - UtopiaValue enumeration index specifying the base key. +* @param[in] pszName - Null-terminated string used as the name index. +* +* @return The status of the operation. +* @retval 1 if the named value was successfully unset. +* @retval 0 if the operation failed. +* +*/ extern int Utopia_UnsetNamed(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, char* pszName); -/* - * Procedure : Utopia_UnsetNamed2 - * Purpose : Unset a Utopia value with a key that is two-dimensionally indexed by strings - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * ixUtopia - UtopiaValue index - * pszName1 - Index string 1 - * pszName2 - Index string 2 - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Unset a Utopia value with a key that is two-dimensionally indexed by string names. +* +* This function removes/clears the value for a UtopiaValue that uses two-dimensional string-based indexing +* from the configuration system. +* +* @param[in] pUtopiaCtx - Pointer to the UtopiaContext containing the system state. +* @param[in] ixUtopia - UtopiaValue enumeration index specifying the base key. +* @param[in] pszName1 - Null-terminated string for the first name index dimension. +* @param[in] pszName2 - Null-terminated string for the second name index dimension. +* +* @return The status of the operation. +* @retval 1 if the two-dimensionally named value was successfully unset. +* @retval 0 if the operation failed. +* +*/ extern int Utopia_UnsetNamed2(UtopiaContext* pUtopiaCtx, UtopiaValue ixUtopia, char* pszName1, char* pszName2); /* @@ -987,15 +1114,19 @@ typedef enum _Utopia_Event Utopia_Event__LAST__ = 0x200000 } Utopia_Event; -/* - * Procedure : Utopia_SetEvent - * Purpose : Set a Utopia event to be triggered on context free - * Parameters : - * pUtopiaCtx - UtopiaContext pointer - * event - Utopia event to be triggered - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Set a Utopia event to be triggered on context free. +* +* This function marks a Utopia event to be triggered when the context is freed using Utopia_Free(). +* +* @param[in] pUtopiaCtx - Pointer to the UtopiaContext where the event will be registered. +* @param[in] event - Utopia_Event enumeration value specifying which event to trigger. +* +* @return The status of the operation. +* @retval 1 if the event was successfully set. +* @retval 0 if the operation failed. +* +*/ extern int Utopia_SetEvent(UtopiaContext* pUtopiaCtx, Utopia_Event event); #endif /* __UTCTX_API_H__ */ diff --git a/source/utctx/lib/utctx_rwlock.h b/source/utctx/lib/utctx_rwlock.h index 0d20e52d..5b3c445c 100644 --- a/source/utctx/lib/utctx_rwlock.h +++ b/source/utctx/lib/utctx_rwlock.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -64,53 +64,79 @@ typedef struct _UtopiaRWLock } UtopiaRWLock; -/* - * Procedure : UtopiaRWLock_Init - * Purpose : Initialize Utopia rwlock - * Parameters : - * pLock - UtopiaRWLock pointer - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Initialize Utopia read/write lock. +* +* This function initializes a UtopiaRWLock structure by clearing the read and write lock flags +* and initializing the underlying semaphore resources. +* +* @param[in,out] pLock - Pointer to the UtopiaRWLock structure to initialize. +* \n Must be allocated by the caller. +* +* @return The status of the operation. +* @retval 1 if the lock was successfully initialized. +* @retval 0 if the operation failed. +* +*/ extern int UtopiaRWLock_Init(UtopiaRWLock* pLock); -/* - * Procedure : UtopiaRWLock_Destroy - * Purpose : Destroy Utopia rwlock - * Parameters : - * pLock - UtopiaRWLock pointer - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Destroy Utopia read/write lock. +* +* This function destroys a UtopiaRWLock structure by releasing the underlying semaphore resources. +* +* @param[in,out] pLock - Pointer to the UtopiaRWLock structure to destroy. +* +* @return The status of the operation. +* @retval 1 if the lock was successfully destroyed. +* @retval 0 if the operation failed. +* +*/ extern int UtopiaRWLock_Destroy(UtopiaRWLock* pLock); -/* - * Procedure : UtopiaRWLock_ReadLock - * Purpose : Acquires a read lock if there isn't already a read or a write lock. - * Parameters : - * pLock - UtopiaRWLock pointer - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Acquire a read lock if there isn't already a read or write lock. +* +* This function attempts to acquire a read lock on the UtopiaRWLock structure. If the lock already +* holds either a read or write lock, the function returns immediately with success. +* +* @param[in,out] pLock - Pointer to the UtopiaRWLock structure on which to acquire a read lock. +* +* @return The status of the operation. +* @retval 1 if the read lock was successfully acquired or already held. +* @retval 0 if the operation failed. +* +*/ extern int UtopiaRWLock_ReadLock(UtopiaRWLock* pLock); -/* - * Procedure : UtopiaRWLock_WriteLock - * Purpose : Acquires a write lock if there isn't already a write lock. If there is a read lock, it will be released. - * Parameters : - * pLock - UtopiaRWLock pointer - * Return Values : - * 1 on success, 0 on error - */ +/** +* @brief Acquire a write lock, releasing any read lock if present. +* +* This function attempts to acquire an exclusive write lock on the UtopiaRWLock structure. If the lock +* already holds a write lock, the function returns immediately with success. If a read lock is currently +* held, it will be automatically released before acquiring the write lock. Only one writer can hold a +* write lock at a time. +* +* @param[in,out] pLock - Pointer to the UtopiaRWLock structure on which to acquire a write lock. +* +* @return The status of the operation. +* @retval 1 if the write lock was successfully acquired or already held. +* @retval 0 if the operation failed. +* +*/ extern int UtopiaRWLock_WriteLock(UtopiaRWLock* pLock); -/* - * Procedure : UtopiaRWLock_Free - * Purpose : Release locks and free up resources - * Parameters : - * pLock - UtopiaRWLock pointer - * Return Values : - */ +/** +* @brief Release locks and free up semaphore resources. +* +* This function releases any currently held read or write locks and closes the underlying semaphore +* resources. It clears both the read lock and write lock flags and releases the associated semaphores. +* +* @param[in,out] pLock - Pointer to the UtopiaRWLock structure to free. +* +* @return None. +* +*/ extern void UtopiaRWLock_Free(UtopiaRWLock* pLock); #endif /* __UTCTX_RWLOCK_H__ */ diff --git a/source/utctx/unittest/src/unittest_syscfg.h b/source/utctx/unittest/src/unittest_syscfg.h index a356fda2..b65309be 100644 --- a/source/utctx/unittest/src/unittest_syscfg.h +++ b/source/utctx/unittest/src/unittest_syscfg.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -40,11 +40,107 @@ #ifndef __UNITTEST_SYSCFG_H__ #define __UNITTEST_SYSCFG_H__ +/** +* @brief Commit all system configuration values to persistent storage. +* +* This function writes all system configuration key-value pairs from the in-memory linked list +* to the UTCTX_STATE_FILE. After writing, all nodes in the linked list are freed. +* +* @return None. +* +*/ extern void SysCfg_Commit(void); + +/** +* @brief Initialize system configuration by loading from persistent storage. +* +* This function initializes the system configuration subsystem by reading configuration values +* from the UTCTX_STATE_FILE and populating an in-memory linked list. The function zeros out the global head +* pointer before loading. +* +* @return The status of the operation. +* @retval 1 if the configuration was successfully initialized. +* @retval 0 if the operation failed (file not found, parse error, or memory allocation error). +* +*/ extern int SysCfg_Init(void); + +/** +* @brief Retrieve a system configuration value by namespace and key. +* +* This function searches the in-memory configuration linked list for a matching namespace and key +* combination, and copies the associated value to the provided buffer. +* +* @param[in] pszNamespace - Null-terminated string specifying the namespace to search. +* @param[in] pszKey - Null-terminated string specifying the key to retrieve. +* \n Must not be NULL. +* @param[out] pszValue - Pointer to a buffer where the configuration value will be stored. +* \n Must be allocated by the caller. +* @param[in] cbBuf - Size of the output buffer in bytes. +* +* @return The status of the operation. +* @retval 1 if the configuration value was successfully retrieved. +* @retval 0 if the operation failed (NULL key, NULL value buffer, or key not found). +* +*/ extern int SysCfg_Get(char* pszNamespace, char* pszKey, char* pszValue, int cbBuf); + +/** +* @brief Retrieve all system configuration values in a single buffer. +* +* This function retrieves all configuration key-value pairs from the in-memory linked list and +* formats them into a single buffer. +* +* @param[out] pBuffer - Pointer to a buffer where all configuration values will be stored. +* \n Each entry is null-terminated and formatted as 'namespace::key=value'. +* \n Must be allocated by the caller. +* @param[in] ccbBuf - Size of the output buffer in bytes. +* @param[out] pccbBuf - Pointer to an integer where the total bytes used will be stored. +* \n Must not be NULL. +* +* @return The status of the operation. +* @retval 1 if all configuration values were successfully retrieved. +* @retval 0 if the operation failed (NULL buffer, NULL pccbBuf, or insufficient buffer space). +* +*/ extern int SysCfg_GetAll(char* pBuffer, int ccbBuf, int* pccbBuf); + +/** +* @brief Set a system configuration value by namespace and key. +* +* This function sets a configuration value in the in-memory linked list. If the namespace and key +* combination already exists, the value is updated. If it doesn't exist, a new node is created and +* appended to the end of the linked list. +* +* @param[in] pszNamespace - Null-terminated string specifying the namespace. +* @param[in] pszKey - Null-terminated string specifying the key to set. +* \n Must not be NULL. +* @param[in] pszValue - Null-terminated string containing the value to set. +* \n Must not be NULL. +* +* @return The status of the operation. +* @retval 1 if the configuration value was successfully set. +* @retval 0 if the operation failed (NULL key, NULL value, or memory allocation error). +* +*/ extern int SysCfg_Set(char* pszNamespace, char* pszKey, char* pszValue); + +/** +* @brief Unset (remove) a system configuration value by namespace and key. +* +* This function searches the in-memory configuration linked list for a matching namespace and key +* combination and removes the node from the list. +* +* @param[in] pszNamespace - Null-terminated string specifying the namespace to search. +* \n Pass NULL to search for keys without a namespace. +* @param[in] pszKey - Null-terminated string specifying the key to unset. +* \n Must not be NULL. +* +* @return The status of the operation. +* @retval 1 if the configuration value was successfully unset. +* @retval 0 if the operation failed (NULL key or key not found). +* +*/ extern int SysCfg_Unset(char* pszNamespace, char* pszKey); #endif /* __UNITTEST_SYSCFG_H__ */ diff --git a/source/util/print_uptime/print_uptime.h b/source/util/print_uptime/print_uptime.h index 3da77567..cf4da50d 100644 --- a/source/util/print_uptime/print_uptime.h +++ b/source/util/print_uptime/print_uptime.h @@ -1,15 +1,15 @@ /************************************************************************************ If not stated otherwise in this file or this component's Licenses.txt file the following copyright and licenses apply: - + Copyright 2018 RDK Management - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -17,5 +17,25 @@ limitations under the License. **************************************************************************/ +/** +* @brief Print and log system uptime with telemetry event reporting. +* +* This function logs the system uptime to a boot time log file and triggers telemetry 2.0 events +* for various system readiness milestones. The function prevents duplicate log entries +* by checking if the uptimeLog marker already exists in the file. +* +* @param[in] uptimeLog - Null-terminated string specifying the uptime log marker/event name. +* \n Used to identify the specific boot milestone being logged. +* \n Triggers corresponding telemetry 2.0 events. +* @param[in] bootfile - Null-terminated string specifying the path to the boot log file. +* \n Pass NULL to use the default file /rdklogs/logs/BootTime.log. +* \n If specified, this custom path will be used instead of the default. +* @param[in] uptime - Null-terminated string representation of uptime in seconds. +* \n Pass NULL to use the current system uptime from sysinfo(). +* \n If provided, this value is used instead of querying the system. +* +* @return None. +* +*/ void print_uptime(char *uptimeLog, char *bootfile, char *uptime); diff --git a/source/util/rpc/client/rpc_client.h b/source/util/rpc/client/rpc_client.h index 5ac5056d..1e2ce95d 100644 --- a/source/util/rpc/client/rpc_client.h +++ b/source/util/rpc/client/rpc_client.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -37,7 +37,7 @@ * @file rpc_client.h * @author Comcast Inc * @date 13 May 2013 - * @brief rpc client initialising api declaration + * @brief rpc client initialising api declaration */ #ifndef RPCCLIENT_H @@ -48,21 +48,46 @@ //static CLIENT *clnt; /** - * @brief Function to initialise rpc client - * - * @param mainArgv - ipaddress of machine where daemon is running - * @return None - * - */ +* @brief Initialize RPC client and establish connection to RPC server daemon. +* +* This function initializes the RPC client by storing the server IP address and creating +* a client connection using clnt_create() with TCP protocol. +* +* @param[in] mainArgv - Null-terminated string containing the IP address of the machine where +* \n the RPC daemon is running. +* \n Maximum length is limited by rpcServerIp buffer size. +* +* @return The status of the RPC connection. +* @retval 1 if the RPC connection was successfully established. +* @retval 0 if the RPC connection failed. +* +*/ int initRPC(char* mainArgv); /** - * @brief Function to get rpc client instance - * - * @param None - * @return CLIENT pointer -rpc client instance - * - */ +* @brief Retrieve the RPC client instance. +* +* This function returns a pointer to the global RPC CLIENT instance that was created during +* initRPC(). The CLIENT pointer is used to make RPC calls to the remote server. +* +* @return Pointer to the RPC CLIENT instance. +* @retval CLIENT* pointer if the RPC client is initialized. +* @retval NULL if the RPC client is not initialized or connection failed. +* +*/ CLIENT* getClientInstance(); + +/** +* @brief Check if RPC connection loss occurred based on error string. +* +* This function examines an error string to determine if it indicates an RPC connection loss. +* +* @param[in] errString - Null-terminated string containing the error message to analyze.. +* +* @return Boolean indicating whether the error represents a connection loss. +* @retval true if the error string contains "Connection reset by peer". +* @retval false if the error string does not indicate a connection loss. +* +*/ bool isRPCConnectionLoss(char* errString); -#endif +#endif \ No newline at end of file diff --git a/source/util/rpc/client/rpc_specification.h b/source/util/rpc/client/rpc_specification.h index 8bffeccb..0aaf52a6 100644 --- a/source/util/rpc/client/rpc_specification.h +++ b/source/util/rpc/client/rpc_specification.h @@ -24,29 +24,156 @@ typedef struct rpc_CommandBuf rpc_CommandBuf; #if defined(__STDC__) || defined(__cplusplus) #define EXECUTECOMMAND 1 +/** +* @brief Execute a shell command on the RPC server and return its output. +* +* @param[in] argp - Pointer to rpc_CommandBuf structure containing the command string to execute. +* @param[in] clnt - Pointer to CLIENT handle for the RPC connection. +* +* @return Pointer to rpc_CommandBuf structure containing command output. +* @retval Pointer to static rpc_CommandBuf containing command output on success. +* @retval NULL if RPC call fails (RPC_SUCCESS not returned) or command execution fails on server. +* +*/ extern rpc_CommandBuf * executecommand_1(rpc_CommandBuf *, CLIENT *); + +/** +* @brief Server-side handler to execute a shell command and return its output. +* +* This function is called by the RPC server dispatcher when the EXECUTECOMMAND procedure is invoked. +* +* @param[in] argp - Pointer to rpc_CommandBuf structure containing the command string. +* @param[in] rqstp - Pointer to svc_req structure containing RPC request information. +* +* @return Pointer to static rpc_CommandBuf containing command output. +* @retval Pointer to static output buffer containing command results on success. +* @retval NULL if popen() fails (errno indicates error). +* +*/ extern rpc_CommandBuf * executecommand_1_svc(rpc_CommandBuf *, struct svc_req *); #define exec 2 +/** +* @brief Execute a shell command on the RPC server in background mode without waiting for output. +* +* This function sends a command string to the RPC server for background execution. +* +* @param[in] argp - Pointer to rpc_CommandBuf structure containing the command string to execute. +* @param[in] clnt - Pointer to CLIENT handle for the RPC connection. +* +* @return Pointer to integer result value. +* @retval Pointer to static integer (value 1) on successful RPC call. +* @retval NULL if RPC call fails (RPC_SUCCESS not returned). +* +*/ extern int * exec_1(rpc_CommandBuf *, CLIENT *); + +/** +* @brief Server-side handler to execute a shell command in background mode. +* +* This function is called by the RPC server dispatcher when the exec procedure is invoked. +* +* @param[in] cmd - Pointer to rpc_CommandBuf structure containing the command string. +* @param[in] req - Pointer to svc_req structure containing RPC request information. +* +* @return Pointer to static integer result. +* @retval Pointer to static integer (value 1) indicating successful command submission. +* +*/ extern int * exec_1_svc(rpc_CommandBuf *, struct svc_req *); + +/** +* @brief Free the result memory allocated by RPC server procedures. +* +* This function is called by the RPC server framework to deallocate memory used by procedure results. +* +* @param[in] transp - Pointer to SVCXPRT transport handle for the RPC connection. +* @param[in] xdr_result - XDR procedure to free the result structure. +* @param[in] result - Pointer to the result structure to be freed. +* +* @return Status of the free operation. +* +*/ extern int rpc_tool1_1_freeresult (SVCXPRT *, xdrproc_t, caddr_t); #else /* K&R C */ #define EXECUTECOMMAND 1 +/** +* @brief Execute a shell command on the RPC server and return its output (K&R C style). +* +* @return Pointer to rpc_CommandBuf structure containing command output. +* @retval Pointer to static rpc_CommandBuf containing command output on success. +* @retval NULL if RPC call fails (RPC_SUCCESS not returned) or command execution fails on server. +* +*/ extern rpc_CommandBuf * executecommand_1(); +/** +* @brief Server-side handler to execute a shell command and return its output (K&R C style). +* +* @return Pointer to static rpc_CommandBuf containing command output. +* @retval Pointer to static output buffer containing command results on success. +* @retval NULL if popen() fails (errno indicates error). +* +*/ extern rpc_CommandBuf * executecommand_1_svc(); #define exec 2 +/** +* @brief Execute a shell command on the RPC server in background mode (K&R C style). +* +* @return Pointer to integer result value. +* @retval Pointer to static integer (value 1) on successful RPC call. +* @retval NULL if RPC call fails (RPC_SUCCESS not returned). +* +*/ extern int * exec_1(); + +/** +* @brief Server-side handler to execute a shell command in background mode (K&R C style). +* +* @return Pointer to static integer result. +* @retval Pointer to static integer (value 1) indicating successful command submission. +* +*/ extern int * exec_1_svc(); + +/** +* @brief Free the result memory allocated by RPC server procedures (K&R C style). +* +* @return Status of the free operation. +* +*/ extern int rpc_tool1_1_freeresult (); #endif /* K&R C */ /* the xdr functions */ #if defined(__STDC__) || defined(__cplusplus) +/** +* @brief XDR serialization/deserialization routine for rpc_CommandBuf structure. +* +* This function handles the XDR encoding and decoding of rpc_CommandBuf structures for RPC transmission. +* +* @param[in,out] xdrs - Pointer to XDR stream handle. +* \n Direction (encode/decode) is determined by the XDR stream mode. +* @param[in,out] objp - Pointer to rpc_CommandBuf structure to serialize or deserialize. +* \n On encode, contains data to be marshalled. +* \n On decode, receives unmarshalled data. +* +* @return Boolean indicating success or failure of XDR operation. +* @retval TRUE if serialization/deserialization succeeded. +* @retval FALSE if operation fails. +* +*/ extern bool_t xdr_rpc_CommandBuf (XDR *, rpc_CommandBuf*); #else /* K&R C */ +/** +* @brief XDR serialization/deserialization routine for rpc_CommandBuf structure (K&R C style). +* +* @return Boolean indicating success or failure of XDR operation. +* @retval TRUE if serialization/deserialization succeeded. +* @retval FALSE if operation failed. +* +*/ extern bool_t xdr_rpc_CommandBuf (); #endif /* K&R C */ diff --git a/source/util/rpc/server/rpc_specification.h b/source/util/rpc/server/rpc_specification.h index 58257606..3f074ef7 100644 --- a/source/util/rpc/server/rpc_specification.h +++ b/source/util/rpc/server/rpc_specification.h @@ -43,29 +43,173 @@ typedef struct rpc_CommandBuf rpc_CommandBuf; #if defined(__STDC__) || defined(__cplusplus) #define EXECUTECOMMAND 1 + +/** +* @brief Execute a shell command on the RPC server and return its output. +* +* @param[in] arg1 - Pointer to rpc_CommandBuf structure containing the command string to execute. +* \n The buffer field must contain a valid null-terminated command string. +* \n Maximum command length is 4096 bytes including null terminator. +* @param[in] arg2 - Pointer to CLIENT handle for the RPC connection. +* \n Must be a valid CLIENT pointer obtained from clnt_create(). +* +* @return Pointer to rpc_CommandBuf structure containing command output. +* @retval Pointer to static rpc_CommandBuf containing command output on success. +* @retval NULL if RPC call fails (RPC_SUCCESS not returned) or command execution fails on server. +* +*/ extern rpc_CommandBuf * executecommand_1(rpc_CommandBuf *, CLIENT *); + +/** +* @brief Server-side handler to execute a shell command and return its output. +* +* This function is called by the RPC server dispatcher when the EXECUTECOMMAND procedure is invoked. + +* +* @param[in] argp - Pointer to rpc_CommandBuf structure containing the command string. +* \n The buffer field must contain a valid null-terminated command string. +* \n Maximum command length is 4096 bytes. +* @param[in] rqstp - Pointer to svc_req structure containing RPC request information. +* +* @return Pointer to static rpc_CommandBuf containing command output. +* @retval Pointer to static output buffer containing command results on success. +* @retval NULL if popen() fails (errno indicates error). +* +*/ extern rpc_CommandBuf * executecommand_1_svc(rpc_CommandBuf *, struct svc_req *); #define exec 2 + +/** +* @brief Execute a shell command on the RPC server in background mode without waiting for output. +* +* This function sends a command string to the RPC server for background execution. + +* +* @param[in] arg1 - Pointer to rpc_CommandBuf structure containing the command string to execute. +* \n The buffer field must contain a valid null-terminated command string. +* \n Maximum command length is 4096 bytes including null terminator. +* @param[in] arg2 - Pointer to CLIENT handle for the RPC connection. +* \n Must be a valid CLIENT pointer obtained from clnt_create(). +* +* @return Pointer to integer result value. +* @retval Pointer to static integer (value 1) on successful RPC call. +* @retval NULL if RPC call fails (RPC_SUCCESS not returned). +* +*/ extern int * exec_1(rpc_CommandBuf *, CLIENT *); + +/** +* @brief Server-side handler to execute a shell command in background mode. +* +* This function is called by the RPC server dispatcher when the exec procedure is invoked. +* +* @param[in] cmd - Pointer to rpc_CommandBuf structure containing the command string. +* \n The buffer field must contain a valid null-terminated command string. +* \n Maximum command length is 4096 bytes. +* @param[in] req - Pointer to svc_req structure containing RPC request information. +* +* @return Pointer to static integer result. +* @retval Pointer to static integer (value 1) indicating successful command submission. +* +*/ extern int * exec_1_svc(rpc_CommandBuf *, struct svc_req *); + +/** +* @brief Free the result memory allocated by RPC server procedures. +* +* This function is called by the RPC server framework to deallocate memory used by procedure results. +* +* @param[in] transp - Pointer to SVCXPRT transport handle for the RPC connection. +* @param[in] xdr_result - XDR procedure to free the result structure. +* @param[in] result - Pointer to the result structure to be freed. +* +* @return Status of the free operation. +* +*/ extern int rpc_tool1_1_freeresult (SVCXPRT *, xdrproc_t, caddr_t); #else /* K&R C */ #define EXECUTECOMMAND 1 + +/** +* @brief Execute a shell command on the RPC server and return its output (K&R C style). +* +* @return Pointer to rpc_CommandBuf structure containing command output. +* @retval Pointer to static rpc_CommandBuf containing command output on success. +* @retval NULL if RPC call fails (RPC_SUCCESS not returned) or command execution fails on server. +* +*/ extern rpc_CommandBuf * executecommand_1(); + +/** +* @brief Server-side handler to execute a shell command and return its output (K&R C style). +* +* @return Pointer to static rpc_CommandBuf containing command output. +* @retval Pointer to static output buffer containing command results on success. +* @retval NULL if popen() fails (errno indicates error). +* +*/ extern rpc_CommandBuf * executecommand_1_svc(); #define exec 2 + +/** +* @brief Execute a shell command on the RPC server in background mode (K&R C style). +* +* @return Pointer to integer result value. +* @retval Pointer to static integer (value 1) on successful RPC call. +* @retval NULL if RPC call fails (RPC_SUCCESS not returned). +* +*/ extern int * exec_1(); + +/** +* @brief Server-side handler to execute a shell command in background mode (K&R C style). +* +* @return Pointer to static integer result. +* @retval Pointer to static integer (value 1) indicating successful command submission. +* +*/ extern int * exec_1_svc(); + +/** +* @brief Free the result memory allocated by RPC server procedures (K&R C style). +* +* @return Status of the free operation. +* +*/ extern int rpc_tool1_1_freeresult (); #endif /* K&R C */ /* the xdr functions */ #if defined(__STDC__) || defined(__cplusplus) +/** +* @brief XDR serialization/deserialization routine for rpc_CommandBuf structure. +* +* This function handles the XDR encoding and decoding of rpc_CommandBuf structures for RPC transmission. +* +* @param[in,out] xdrs - Pointer to XDR stream handle. +* \n Direction (encode/decode) is determined by the XDR stream mode. +* @param[in,out] objp - Pointer to rpc_CommandBuf structure to serialize or deserialize. +* \n On encode, contains data to be marshalled. +* \n On decode, receives unmarshalled data. +* +* @return Boolean indicating success or failure of XDR operation. +* @retval TRUE if serialization/deserialization succeeded. +* @retval FALSE if operation failed. +* +*/ extern bool_t xdr_rpc_CommandBuf (XDR *, rpc_CommandBuf*); #else /* K&R C */ +/** +* @brief XDR serialization/deserialization routine for rpc_CommandBuf structure (K&R C style). +* +* @return Boolean indicating success or failure of XDR operation. +* @retval TRUE if serialization/deserialization succeeded. +* @retval FALSE if operation failed. +* +*/ extern bool_t xdr_rpc_CommandBuf (); #endif /* K&R C */ diff --git a/source/util/utils/util.h b/source/util/utils/util.h index af55af46..376feef4 100644 --- a/source/util/utils/util.h +++ b/source/util/utils/util.h @@ -19,13 +19,13 @@ /********************************************************************** Copyright [2014] [Cisco Systems, Inc.] - + Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -47,17 +47,160 @@ #define MANAGE_WIFI_PSM_STR "dmsb.MultiLAN.ManageWiFi_l3net" #define MANAGE_WIFI_BRIDGE_NAME "dmsb.l2net.%s.Name" #define MANAGE_WIFI_V4_ADDR "dmsb.l3net.%s.V4Addr" + +/** +* @brief Update DHCP pool configuration data to dnsmasq configuration file. +* +* This function retrieves DHCP pool settings from PSM and writes them to the dnsmasq configuration file. +* +* @param[in] bus_handle - Pointer to the message bus handle for PSM communication. +* @param[in] pIndex - Pointer to string containing the DHCP pool index. +* @param[in,out] pFile - Pointer to FILE handle for the dnsmasq configuration file. +* +* @return None. +* +*/ void updateDhcpPoolData(void * bus_handle, char * pIndex, FILE * pFile); #endif /* WIFI_MANAGE_SUPPORTED*/ +/** +* @brief Retrieve a parameter value from PSM (Persistent Storage Manager). +* +* This function retrieves a parameter value from PSM using the CCSP message bus. +* +* @param[in] bus_handle - Pointer to the CCSP message bus handle. +* @param[in] pParamName - Pointer to the PSM parameter name string. +* @param[out] pParamValue - Pointer to buffer where the parameter value will be stored. +* @param[in] len - Size of the pParamValue buffer in bytes. +* +* @return None. +* +*/ void psmGet(void *bus_handle, char *pParamName, char *pParamValue, size_t len); + +/** +* @brief Execute a shell command with printf-style formatting. +* +* This function constructs a shell command from a format string and variable arguments, then executes it using system(). +* +* @param[in] fmt - Format string for the command (printf-style). +* @param[in] ... - Variable arguments corresponding to format specifiers in fmt. +* +* @return Status of the command execution. +* @retval Exit status returned by system() on successful command execution. +* @retval -1 if fails +* +*/ int vsystem(const char *fmt, ...); + +/** +* @brief Set a sysctl parameter for a network interface. +* +* This function writes a value to a sysctl file, optionally formatting the path with an interface name. +* +* @param[in] path - Path to the sysctl file, optionally containing a %s format specifier for ifname. +* @param[in] ifname - Interface name to substitute into path (can be NULL). +* @param[in] content - Content string to write to the sysctl file. +* +* @return Status of the operation. +* @retval 0 if the sysctl parameter was successfully written. +* @retval -1 if opening or writing to the file fails. +* +*/ int sysctl_iface_set(const char *path, const char *ifname, const char *content); + +/** +* @brief Get the hardware (MAC) address of a network interface. +* +* This function retrieves the MAC address of the specified network interface. +* +* @param[in] ifname - Name of the network interface (e.g., "eth0", "wlan0"). +* @param[out] mac - Pointer to buffer where the MAC address string will be stored. +* @param[in] size - Size of the mac buffer in bytes. +* +* @return Status of the operation. +* @retval 0 if the MAC address was successfully retrieved and stored. +* @retval -1 if parameters are invalid, socket creation fails, interface is not present, or ioctl fails. +* +*/ int iface_get_hwaddr(const char *ifname, char *mac, size_t size); + +/** +* @brief Get the IPv4 address of a network interface. +* +* This function retrieves the IPv4 address of the specified network interface. +* +* @param[in] ifname - Name of the network interface. +* @param[out] ipv4Addr - Pointer to buffer where the IPv4 address string will be stored. + +* @param[in] size - Size of the ipv4Addr buffer in bytes. +* +* @return Status of the operation. +* @retval 0 if the IPv4 address was successfully retrieved and stored. +* @retval -1 if parameters are invalid, socket creation fails, interface is not present, or ioctl fails. +* +*/ int iface_get_ipv4addr(const char *ifname, char *ipv4Addr, size_t size); + +/** +* @brief Check if a network interface is present in the system. +* +* This function checks whether the specified network interface exists. +* +* @param[in] ifname - Name of the network interface to check. +* +* @return Interface presence status. +* @retval 1 if the interface is present and operational. +* @retval 0 if the interface is not present, parameters are invalid, or any error occurs. +* +*/ int is_iface_present(const char *ifname); +/** +* @brief Check if a service can be started based on its current status. +* +* This function queries the service status from sysevent and determines if the service can be started. +* +* @param[in] sefd - Sysevent file descriptor for communication with sysevent daemon. +* @param[in] tok - Sysevent token for authentication. +* @param[in] servname - Name of the service to check. +* +* @return Service start capability status. +* @retval 1 if the service can be started. +* @retval 0 if the service is already starting, started, or stopping. +* +*/ int serv_can_start(int sefd, token_t tok, const char *servname); + +/** +* @brief Check if a service can be stopped based on its current status. +* +* This function queries the service status from sysevent and determines if the service can be stopped. + +* +* @param[in] sefd - Sysevent file descriptor for communication with sysevent daemon. +* @param[in] tok - Sysevent token for authentication. +* @param[in] servname - Name of the service to check. +* +* @return Service stop capability status. +* @retval 1 if the service can be stopped. +* @retval 0 if the service is already stopping, stopped, or starting. +* +*/ int serv_can_stop(int sefd, token_t tok, const char *servname); + +/** +* @brief Find the process ID (PID) of a running process by name and optional keyword. +* +* This function searches /proc filesystem to find a process matching the specified name. +* +* @param[in] name - Name of the process to search for. +* @param[in] keyword - Optional keyword to search for in the command line (can be NULL). +* +* @return Process ID of the matching process. +* @retval Positive PID value if a matching process is found. +* @retval -1 if no matching process is found or /proc directory cannot be opened. +* +*/ int pid_of(const char *name, const char *keyword); -#endif /* __SW_UTIL__ */ +#endif /* __SERV_UTIL__ */