/* This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ #ifndef _PLAT_API_H_ #define _PLAT_API_H_ #include "cc_constants.h" #include "cpr_socket.h" #include "cc_types.h" /** * Define unregister reason */ #define CC_UNREG_REASON_UNSPECIFIED 0 //Common with what SCCP uses...need to match with J-Side #define CC_UNREG_REASON_TCP_TIMEOUT 10 #define CC_UNREG_REASON_CM_RESET_TCP 12 #define CC_UNREG_REASON_CM_ABORTED_TCP 13 #define CC_UNREG_REASON_CM_CLOSED_TCP 14 #define CC_UNREG_REASON_REG_TIMEOUT 17 #define CC_UNREG_REASON_FALLBACK 18 #define CC_UNREG_REASON_PHONE_KEYPAD 20 #define CC_UNREG_REASON_RESET_RESET 22 #define CC_UNREG_REASON_RESET_RESTART 23 #define CC_UNREG_REASON_PHONE_REG_REJ 24 #define CC_UNREG_REASON_PHONE_INITIALIZED 25 #define CC_UNREG_REASON_VOICE_VLAN_CHANGED 26 #define CC_UNREG_REASON_POWER_SAVE_PLUS 32 //sip specific ones...need to match with J-Side #define CC_UNREG_REASON_VERSION_STAMP_MISMATCH 100 #define CC_UNREG_REASON_VERSION_STAMP_MISMATCH_CONFIG 101 #define CC_UNREG_REASON_VERSION_STAMP_MISMATCH_SOFTKEY 102 #define CC_UNREG_REASON_VERSION_STAMP_MISMATCH_DIALPLAN 103 #define CC_UNREG_REASON_APPLY_CONFIG_RESTART 104 #define CC_UNREG_REASON_CONFIG_RETRY_RESTART 105 #define CC_UNREG_REASON_TLS_ERROR 106 #define CC_UNREG_REASON_RESET_TO_INACTIVE_PARTITION 107 #define CC_UNREG_REASON_VPN_CONNECTIVITY_LOST 108 #define CC_IPPROTO_UDP 17 #define CC_IPPROTO_TCP 6 /** * socket security status */ typedef enum { PLAT_SOCK_SECURE, PLAT_SOCK_NONSECURE } plat_soc_status_e; /** * socket connection status */ typedef enum { PLAT_SOCK_CONN_OK, PLAT_SOCK_CONN_WAITING, PLAT_SOCK_CONN_FAILED } plat_soc_connect_status_e; /** * socket connection type */ typedef enum { PLAT_SOCK_CUCM } plat_soc_connect_type_e; /** * socket connection mode */ typedef enum { PLAT_SOCK_AUTHENTICATED, PLAT_SOCK_ENCRYPTED, PLAT_SOCK_NON_SECURE } plat_soc_connect_mode_e; /** * psipcc core debug categories */ typedef enum { CC_DEBUG_CCAPP, CC_DEBUG_CONFIG_CACHE, CC_DEBUG_SIP_ADAPTER, CC_DEBUG_CCAPI, CC_DEBUG_CC_MSG, CC_DEBUG_FIM, CC_DEBUG_FSM, CC_DEBUG_AUTH, CC_DEBUG_GSM, CC_DEBUG_LSM, CC_DEBUG_FSM_CAC, CC_DEBUG_DCSM, CC_DEBUG_SIP_TASK, CC_DEBUG_SIP_STATE, CC_DEBUG_SIP_MSG, CC_DEBUG_SIP_REG_STATE, CC_DEBUG_SIP_TRX, CC_DEBUG_TIMERS, CC_DEBUG_SIP_DM, CC_DEBUG_CCDEFAULT, /* Always ON by default */ CC_DEBUG_DIALPLAN, CC_DEBUG_KPML, CC_DEBUG_REMOTE_CC, CC_DEBUG_SIP_PRESENCE, CC_DEBUG_CONFIG_APP, CC_DEBUG_CALL_EVENT, CC_DEBUG_PLAT, CC_DEBUG_NOTIFY, CC_DEBUG_CPR_MEMORY, /* Has additional parameters - Tracking/poison */ CC_DEBUG_MAX /* NOT USED */ } cc_debug_category_e; /** * debug show categories */ typedef enum { CC_DEBUG_SHOW_FSMCNF, CC_DEBUG_SHOW_FSMDEF, CC_DEBUG_SHOW_FSMXFR, CC_DEBUG_SHOW_FSMB2BCNF, CC_DEBUG_SHOW_DCSM, CC_DEBUG_SHOW_FIM, CC_DEBUG_SHOW_FSM, CC_DEBUG_SHOW_LSM, CC_DEBUG_SHOW_BULK_REGISTER, CC_DEBUG_SHOW_KPML, CC_DEBUG_SHOW_REMOTE_CC, CC_DEBUG_SHOW_CONFIG_CACHE, CC_DEBUG_SHOW_SUBS_STATS, CC_DEBUG_SHOW_PUBLISH_STATS, CC_DEBUG_SHOW_REGISTER, CC_DEBUG_SHOW_DIALPLAN, CC_DEBUG_SHOW_CPR_MEMORY, /* Has additional parameters - config/heap-gaurd/stat/tracking. */ CC_DEBUG_SHOW_MAX } cc_debug_show_options_e; /** * debug clear categories */ typedef enum { CC_DEBUG_CLEAR_CPR_MEMORY, CC_DEBUG_CLEAR_MAX } cc_debug_clear_options_e; /** * cpr memory debug sub-categories */ typedef enum { CC_DEBUG_CPR_MEM_TRACKING, CC_DEBUG_CPR_MEM_POISON } cc_debug_cpr_mem_options_e; /** * cpr memory clear sub-commands */ typedef enum { CC_DEBUG_CLEAR_CPR_TRACKING, CC_DEBUG_CLEAR_CPR_STATISTICS } cc_debug_clear_cpr_options_e; /** * cpr memory show sub-commands */ typedef enum { CC_DEBUG_SHOW_CPR_CONFIG, CC_DEBUG_SHOW_CPR_HEAP_GUARD, CC_DEBUG_SHOW_CPR_STATISTICS, CC_DEBUG_SHOW_CPR_TRACKING } cc_debug_show_cpr_options_e; /** * Enabling/disabling debugs */ typedef enum { CC_DEBUG_DISABLE, CC_DEBUG_ENABLE } cc_debug_flag_e; // Corresponds to the values for XML tags DHCPv4Status and DHCPv6Status typedef enum { DHCP_STATUS_GOOD = 1, DHCP_STATUS_TIMEOUT, DHCP_STATUS_DISABLED } dhcp_status_e; // Corresponds to the value for XML tag for DNSStatusUnifiedCMX typedef enum { DNS_STATUS_GOOD = 1, DNS_STATUS_TIMEOUT, DNS_STATUS_DID_NOT_RESOLVE, DNS_STATUS_NA_IP_CONFIGURED } ucm_dns_resolution_status_e; #define LEN32 32 #define IP_ADDR_MAX_LEN 32 #define PORT_MAX_LEN 20 #define STATUS_MAX_LEN 4 #define LEN80 80 #define WIRED_PROP_PREFIX "dhcp.eth0" #define WIRELESS_PROP_PREFIX "dhcp.mlan0" #define WIRED_INT 1 #define WIFI_INT 2 /** * Called by the thread to initialize any thread specific data * once the thread is created. * * @param[in] tname thread name * * @return 0 - SUCCESS * -1 - FAILURE */ int platThreadInit(char * tname); /** * The initial initialization function for any platform related * modules * * * @return 0 - SUCCESS * -1 - FAILURE */ int platInit(); /** * The initial initialization function for the debugging/logging * modules * */ void debugInit(); /** * Get device model that will be sent to cucm in the UserAgent header * * @return char * Pointer to the string containing the model number of the phone. */ char *platGetModel(); /** * plat_audio_device_t * Enums for indicating audio device */ typedef enum vcm_audio_device_type { VCM_AUDIO_DEVICE_NONE, VCM_AUDIO_DEVICE_HEADSET, VCM_AUDIO_DEVICE_SPEAKER } plat_audio_device_t; /** * Add cc control classifier * * Called by SIP stack to specify addresses and ports that will be used for call control * * @param[in] myIPAddr - phone local interface IP Address * @param[in] myPort - phone local interface Port * @param[in] cucm1IPAddr - CUCM 1 IP Address * @param[in] cucm1Port - CUCM 1 Port * @param[in] cucm2IPAddr - CUCM 2 IP Address * @param[in] cucm2Port - CUCM 2 Port * @param[in] cucm3IPAddr - CUCM 3 IP Address * @param[in] cucm3Port - CUCM 3 Port * @param[in] protocol - CC_IPPROTO_UDP or CC_IP_PROTO_TCP * * @note : Needed only if using WiFi. If not using Wifi please provide a stub */ void platAddCallControlClassifiers(unsigned long myIPAddr, unsigned short myPort, unsigned long cucm1IPAddr, unsigned short cucm1Port, unsigned long cucm2IPAddr, unsigned short cucm2Port, unsigned long cucm3IPAddr, unsigned short cucm3Port, unsigned char protocol); /** * Remove cc control classifier. * * Undo platAddCallControlClassifiers */ void platRemoveCallControlClassifiers(); /** * Tell whether wifi is supported and active * * @return boolean wether WLAN is active or not */ cc_boolean platWlanISActive(); /** * Check if the netowrk interface changed. * * @return boolean returns TRUE if the network interface has changed * * @note Most common case is for softphone clients where if a PC is * undocked the network interface changes from wired to wireless. */ boolean platIsNetworkInterfaceChanged(); /** * Get active phone load name * * Returns the phone images in the active and inactive partitions * The phone reports these phone loads to CUCM for display on the Admin page * * @param[in] image_a : Populate the image name from partition a * @param[in] image_b : Populate the image name from partition b * @param[in] len : Length of the pointers for image_a and image_b * @return 1 - image_a is active * 2 - image_b is active * -1 - Failure */ int platGetActiveInactivePhoneLoadName(char * image_a, char * image_b, int len); /** * Get localized phrase for the specified index * * @param[in] index the phrase index, see * @param[in] phrase the return phrase holder * @param[in] len the input length to cap the maximum value * * @return SUCCESS or FAILURE */ int platGetPhraseText(int index, char* phrase, unsigned int len); /** * Set the unregistration reason * * @param[in] reason see the unregister reason definitions. * * @note we expect the platform to save this value in Non Volatile memory * This will be retrieved later by using platGetUnregReason. This reason is reported to CUCM */ void platSetUnregReason(int reason); /** * Get the unregistration reason code. * * @return reason code for unregistration */ int platGetUnregReason(); /** * Sets the time based on Date header in 200 OK from REGISTER request * @param void * @return void */ void platSetCucmRegTime (void); /** * Set the kpml value for application. * * @param kpml_config the kpml value */ void platSetKPMLConfig(cc_kpml_config_t kpml_config); /** * Check if a line has active MWI status * * @param line * * @return boolean * * @note The stack doesn't store the MWI status and expects * the application to store that information. The stack * queries the mwi status from the application using this method. */ boolean platGetMWIStatus(cc_lineid_t line); /** * Check if the speaker or headset is enabled. * * @return boolean if the speaker or headset is enabled, returns true. */ boolean platGetSpeakerHeadsetMode(); /** * Secure Socket API's. * The pSIPCC expects the following Secure Socket APIs to be implemented in the * vendor porting layer. */ /** * platSecIsServerSecure * * @brief Lookup the secure status of the server * * This function looks at the the CCM server type by using the security library * and returns appropriate indication to the pSIPCC. * * * @return Server is security enabled or not * PLAT_SOCK_SECURE or PLAT_SOCK_NONSECURE * * @note This API maps to the following HandyIron API: * int secIsServerSecure(SecServerType type) where type should be SRVR_TYPE_CCM */ plat_soc_status_e platSecIsServerSecure(void); /** * platSecSocConnect * @brief Securely connect to a remote server * * This function uses the security library APIs to connect to a remote server. * @param[in] host server addr * @param[in] port port number * @param[in] ipMode IP mode to indicate v6, v4 or both * @param[in] mode blocking connect or not * FALSE: non-blocking; TRUE: blocking * @param[in] tos TOS value * @param[in] connectionMode The mode of the connection * (Authenticated/Encrypted) * @param[out] localPort local port used for the connection * * @return client socket descriptor * >=0: connected or in progress * INVALID SOCKET: failed * * @pre (hostAndPort not_eq NULL) * @pre (localPort not_eq NULL) * * @note localPort is undefined when the return value is INVALID_SOCKET * * @note This API maps to the HandyIron APIs as follows: * If mode == TRUE (blocking): * int secEstablishSecureConnection(const char* serverAddr, *uint32_t port, secConnectionType type) * @li ipMode is UNUSED * @li "host" maps to "serverAddr", "type" should be determined by an application and use the value from SecServerType. * @li localPort is passed in as 0 * If mode == FALSE (non-blocking): * int secConnect(const char* serverAddr, uint32_t port, *secConnectionType type, uint32_t localPort) * @li ipMode is UNUSED * @li "host" maps to "serverAddr", "type" should be determined by an application and use the value from SecServerType. * * @note The implementation should use the "setsockopt" to set the "tos" value passed * in this API on the created socket. * */ cpr_socket_t platSecSocConnect (char *host, int port, int ipMode, boolean mode, unsigned int tos, plat_soc_connect_mode_e connectionMode, cc_uint16_t *localPort); /** * platSecSockIsConnected * Determine the status of a secure connection that was initiated * in non-blocking mode * * @param[in] sock socket descriptor * * @return connection status * @li connection complete: PLAT_SOCK_CONN_OK * @li connection waiting: PLAT_SOCK_CONN_WAITING * @li connection failed: PLAT_SOCK_CONN_FAILED * * @note This API maps to the following HandyIron API: * int secIsConnectionReady (int connDesc) * The "sock" is the connection descriptor. */ plat_soc_connect_status_e platSecSockIsConnected (cpr_socket_t sock); /** * platGenerateCryptoRand * @brief Generates a Random Number * * Generate crypto graphically random number for a desired length. * The function is expected to be much slower than the cpr_rand(). * This function should be used when good random number is needed * such as random number that to be used for SRTP key for an example. * * @param[in] buf - pointer to the buffer to store the result of random * bytes requested. * @param[in] len - pointer to the length of the desired random bytes. * When calling the function, the integer's value * should be set to the desired number of random * bytes ('buf' should be of at least this size). * upon success, its value will be set to the * actual number of random bytes being returned. * (realistically, there is a maximum number of * random bytes that can be returned at a time. * if the caller request more than that, the * 'len' will indicate how many bytes are actually being * returned) on failure, its value will be set to 0. * * @return * 1 - success. * 0 - fail. * * @note The intent of this function is to generate a cryptographically strong * random number. Vendors can map this to HandyIron or OpenSSL random number * generation functions. * * @note This API maps to the following HandyIron API: * int secGetRandomData(uint8_t *buf, uint32_t size). Also note that a * "secAddEntropy(...)" may be required the first time to feed entropy data to * the random number generator. */ int platGenerateCryptoRand(cc_uint8_t *buf, int *len); /** * platSecSocSend * * @brief The platSecSocSend() function is used to send data over a secure * socket. * * The platSecSocSend() function shall transmit a message from the specified socket to * its peer. The platSecSocSend() function shall send a message only when the socket is * connected. The length of the message to be sent is specified by the length * argument. If the message is too long to pass through the underlying protocol, * platSecSocSend() shall fail and no data is transmitted. Delivery of the message is * not guaranteed. * * @param[in] soc Specifies the socket created with cprSocket() to send * @param[in] buf A pointer to the buffer of the message to send. * @param[in] len Specifies the length in bytes of the message pointed to by the buffer argument. * * @return Upon successful completion, platSecSocSend() shall return the number of * bytes sent. Otherwise, SOCKET_ERROR shall be returned and cpr_errno set to * indicate the error. * * @note The possible error values this function should return are * @li [CPR_EBADF] The socket argument is not a valid file descriptor * @li [CPR_ENOTSOCK] socket does not refer to a socket descriptor * @li [CPR_EAGAIN] The socket is marked non-blocking and no data can * be sent * @li [CPR_EWOULDBLOCK] Same as CPR_EAGAIN * @li [CPR_ENOTCONN] A connection-mode socket that is not connected * @li [CPR_ENOTSUPP] The specified flags are not supported for this * type of socket or protocol. * @li [CPR_EMSGSIZE] The message is too large to be sent all at once * @li [CPR_EDESTADDRREQ] The socket has no peer address set * */ ssize_t platSecSocSend (cpr_socket_t soc, CONST void *buf, size_t len); /** * platSecSocRecv * * @brief The platSecSocRecv() function shall receive a message from a secure socket. * * This function is normally used with connected sockets because it does not permit * the application to retrieve the source address of received data. The * platSecSocRecv() function shall return the length of the message written to * the buffer pointed to by the "buf" argument. * * @param[in] soc - Specifies the socket to receive data * @param[out] buf - Contains the data received * @param[out] len - The length of the data received * * @return On success the length of the message in bytes (including zero). * On failure SOCKET_ERROR shall be returned and cpr_errno set to * indicate the error. * * @note The possible error values this function should return are * @li [CPR_EBADF] The socket argument is not a valid file descriptor * @li [CPR_ENOTSOCK] The descriptor references a file, not a socket. * @li [CPR_EAGAIN] The socket is marked non-blocking and no data is * waiting to be received. * @li [CPR_EWOULDBLOCK] Same as CPR_EAGAIN * @li [CPR_ENOTCONN] A receive attempt is made on a connection-mode socket that is not connected * @li [CPR_ENOTSUPP] The specified flags are not supported for this type of socket or protocol * */ ssize_t platSecSocRecv (cpr_socket_t soc, void * RESTRICT buf, size_t len); /** * platSecSocClose * * @brief The platSecSocClose function shall close a secure socket * * The platSecSocClose() function shall destroy the socket descriptor indicated * by socket. * * @param[in] soc - The socket that needs to be destroyed * * @return CPR_SUCCESS on success otherwise, CPR_FAILURE. cpr_errno needs to be set in this case. * * @note The possible error values this function should return are * @li [CPR_EBADF] socket is not a valid socket descriptor. */ cpr_status_e platSecSocClose (cpr_socket_t soc); /** * Sets the SIS protocol version * * @param a - major version * @param b - minor version * @param c - additional version information * @param name - version name * * @return void * @note the platform should store this information and provide it when asked via the platGetSISProtocolVer() */ void platSetSISProtocolVer(cc_uint32_t a, cc_uint32_t b, cc_uint32_t c, char* name); /** * Provides the SIS protocol version * * @param *a pointer to fill in the major version * @param *b pointer to fill in the minor version * @param *c pointer to fill in the additonal version * @param *name pointer to fill in the version name * * @return void */ void platGetSISProtocolVer (cc_uint32_t *a, cc_uint32_t *b, cc_uint32_t *c, char* name); /** * Provides the local IP address * * @return char * returns the local IP address */ char *platGetIPAddr(); /** * Provides the local MAC address * * @param *maddr the pointer to the string holding MAC address * in the MAC address format after converting from string format. * @return void */ void platGetMacAddr(char *addr); /** * platGetFeatureAllowed * * Get whether the feature is allowed * * @param featureId - sis feature id * * @return 1 - allowed, 0 - not allowed * */ int platGetFeatureAllowed(cc_sis_feature_id_e featureId); /** * Set the Status message for failure reasons * @param char *msg * @return void */ void platSetStatusMessage(char *msg); /** * The equivalent of the printf function. * * This function MUST be implemented by the vendors. This is called by the core * library whenever some debugging information needs to be printed out. * call this function in order to clear the CPR Memory/Tracking statistics * * Please also be aware that cpr_stdio.h has other logging functions as well. * Vendors need to implement this function and the functions (err_msg, * buginf....etc) found in cpr_stdio.h * * @param[in] _format format string * @param[in] ... variable arg list * * @return Return code from printf */ int debugif_printf(const char *_format, ...); /** * Enable / disable speaker * * @param[in] state - true -> enable speaker, false -> disable speaker * * @return void */ void platSetSpeakerMode(cc_boolean state); /** * Get the status (on/off) of the audio device * * @param[in] device_type - headset or speaker (see vcm_audio_device_t) * * @return 1 -> On, 0 -> off, ERROR -> unknown (error) */ int platGetAudioDeviceStatus(plat_audio_device_t device_type); /* * Returns the default gateway * * @param void * @return u_long */ cc_ulong_t platGetDefaultgw(); #endif /* _PLATFORM_API_H_ */