/* ipwps_ui.h - IPWPS User Interface header file */
/*
* Copyright (c) 2009 Wind River Systems, Inc.
*
* The right to copy, distribute, modify, or otherwise make use
* of this software may be licensed only pursuant to the terms
* of an applicable Wind River license agreement.
* 
*/

/*
modification history
--------------------
01a,16Mar09,mry  Created
*/
#ifndef IPWPS_UI_H
#define IPWPS_UI_H

/*
 ****************************************************************************
 * 1                    DESCRIPTION
 ****************************************************************************
 */

/* This header file contains the UI definitions and APIs to be used by the 
 * various wps modules to prompt and notify the user of various WPS events.
 * This is not to be confused with the logging APIs that are used for debugging.
 * The UI is strictly for information that needs to be conveyed to users.
 */

/*
 ****************************************************************************
 * 2                    CONFIGURATION
 ****************************************************************************
 */


/*
 ****************************************************************************
 * 3                    INCLUDE FILES
 ****************************************************************************
 */

#include <ipcom_type.h>
#include <ipcom_cstyle.h>

#include "ipwps_common.h"

#ifdef __cplusplus
extern "C" {
#endif

/*
 ****************************************************************************
 * 4                    DEFINES
 ****************************************************************************
 */

/*
 ****************************************************************************
 * 5                    TYPES
 ****************************************************************************
 */
	
typedef enum {
	IPWPS_UI_PROMPT_ENTER_PIN,
	IPWPS_UI_PROMPT_WPS_AP_FOUND,
	IPWPS_UI_PROMPT_WPS_REGISTRAR_FOUND,
	IPWPS_UI_PROMPT_WPS_PBC_ENROLLEE_DETECTED
} Ipwps_ui_prompt_type;	

typedef enum {
	IPWPS_UI_DISPLAY_CRITICAL,
	IPWPS_UI_DISPLAY_ERROR,
	IPWPS_UI_DISPLAY_WARNING,
	IPWPS_UI_DISPLAY_NOTIFICATION,
	IPWPS_UI_DISPLAY_INFO
} Ipwps_ui_display_type;

struct Ipwps_ctx_st;

/*
 ****************************************************************************
 * 6                    FUNCTIONS
 ****************************************************************************
 */
	
/*
 *===========================================================================
 *                    ipwps_ui_display
 *===========================================================================
 * Description:  IPWPS User Interface Display function, which is called by
 *   IPWPS applications to display event that are relevant to the end user. 
 *   The implementation of this function can customized to use a richer UI
 *   NOTE: THIS FUNCTION MUST NOT BLOCK OR PEND. 
 * Parameters:
 *  Ipwps_ui_event_type type - Type of event to display.
 *  const char *string - string to display.
 * Returns:
 *  >= 0 if successful, < 0 if not. 
 */
IP_GLOBAL int ipwps_ui_display
(
		Ipwps_ui_display_type type,
		const char *string
);

/*
 *===========================================================================
 *                    ipwps_ui_prompt
 *===========================================================================
 * Description: IPWPS User Interface Prompt function which is called by 
 *   IPWPS applications to prompt the user to do some action.
 *   The implementation of this function can customized to use a richer UI
 *   NOTE: THIS FUNCTION MUST NOT BLOCK OR PEND. 
 * Parameters:
 *   Ipwps_ui_prompt_type prompt - Type of prompt
 *   const char *string - Message associated with the prompt.
 * Returns:
 *  >= 0 if successful, < 0 if not. 
 */
IP_GLOBAL int ipwps_ui_prompt
(
		Ipwps_ui_prompt_type prompt, 
		const char *string
);

/*
 *===========================================================================
 *                    ipwps_ui_report_wps_status
 *===========================================================================
 * Description:  IPWPS User Interface function which is called by
 *   IPWPS applications to report the WPS status as described in the WPS spec.
 *    
 * Parameters:
 * 	 Ipwps_ctx* ctx - A valid wps context.
 *  Ipwps_session_status status - WPS session status to report.
 *    IPWPS_SESSION_STATUS_IDLE - Indicates WPS session is now idle 
 *                                (clears previous state when an enrollee is started or stopped)
 * 	  IPWPS_SESSION_STATUS_IN_PROGRESS - WPS Session Status "In Progress" 
 *                                       (as per WPS spec)
 *    IPWPS_SESSION_STATUS_ERROR - WPS Session Status "Error" 
 *                                       (as per WPS spec)
 * 	  IPWPS_SESSION_STATUS_SESSION_OVERLAP - WPS Session Status "Session Overlap Detected" 
 *                                       (as per WPS spec)
 * 	  IPWPS_SESSION_STATUS_SUCCESS - WPS Session Status "Success" 
 *                                       (as per WPS spec)
 * 	  IPWPS_ENROLLEE_JOIN_SUCCESS - Indicates that the Enrollee has successfully
 *                                  joined an AP using one of the credentials provided
 *                                  by the registrar. 
 *                                  After this indication is received, an application may use the 
 *                                  "cred = ipwps_api_wps_get_credentials()" api
 *                                  to retrieve the enrollee credentials. The credential set used
 *                                  to join the AP can be obtained by calling 
 *                                  "pub_ctx = ipwps_api_wps_get_public_ctx()" and 
 *                                  retrieving "setno = pub_ctx->enrollee_info.credential_setno".
 *                                  The credential set will be cred->enrollee_credentials[setno]
 *                                  which can be used to retrieve the ssid and other credentials
 *                                  in case they need to be stored in NV memory by an application.                                 
 * 	  IPWPS_ENROLLEE_JOIN_FAIL - Indicates that the Enrollee failed to associate with any 
 *                               of the APs indicated in the credentials provided by the registrar.
 * Returns:
 *  >= 0 if successful, < 0 if not. 
 */
IP_GLOBAL int ipwps_ui_report_wps_status
(
		struct Ipwps_ctx_st* ctx,
		Ipwps_session_status status
);


/*
 ****************************************************************************
 *                      END OF FILE
 ****************************************************************************
 */

#ifdef __cplusplus
}
#endif

#endif