/***********************************************************************
 *  File: auth_token_int.h
 *  Author: Juan Carlos Luciani (jluciani@novell.com)
 * 
 *  Abstract: Defines the interface between the authentication token
 *  module and its providers.
 * 
 *  Copyright (C) 2005 Novell, Inc.
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Lesser General Public
 *  License as published by the Free Software Foundation; version 2.1
 *  of the License.
 *
 *  This library is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  Library General Public License for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with this library; if not, write to the Free
 *  Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 * 
 *  To contact Novell about this file by physical or electronic mail, 
 *  you may find current contact information at www.novell.com. 
 ***********************************************************************/

#ifndef _AUTH_TOKEN_INT_H_
#define _AUTH_TOKEN_INT_H_

#if defined(__cplusplus) || defined(c_plusplus)
extern "C" 
{
#endif

//===[ Include files ]=====================================================

#include <micasa_types.h>
#include <casa_status.h>

//===[ Type definitions ]==================================================

//===[ Function prototypes ]===============================================

//===[ Global variables ]==================================================

/**************************************************************************
***************************************************************************
**                                                                       **
**    Definitions common to all interfaces                               **
**                                                                       **
***************************************************************************
**************************************************************************/


//++=======================================================================
typedef
int       
(SSCS_CALL *PFN_AddReference)(
   IN       const void  *pIfInstance);
//
// Arguments:  
//    pIfInstance -
//       Pointer to interface object.
//   
// Returns:
//    Interface reference count.
//                           
// Description:
//    Increases interface reference count.
//=======================================================================--


//++=======================================================================
typedef
void       
(SSCS_CALL *PFN_ReleaseReference)(
   IN       const void  *pIfInstance);
//
// Arguments:  
//    pIfInstance -
//       Pointer to interface object.
//   
// Returns:
//    Nothing.
//                           
// Description:
//    Decreases interface reference count. The interface is deallocated if
//    the reference count becomes zero.
//=======================================================================--



/**************************************************************************
***************************************************************************
**                                                                       **
**    Configuration Object Interface Definitions                         **
**                                                                       **
***************************************************************************
**************************************************************************/


//++=======================================================================
typedef
char*
(SSCS_CALL *PFN_GetEntryValue)(
   IN       const void  *pIfInstance,
   IN       const char  *pKeyName);
//
// Arguments:  
//    pIfInstance -
//       Pointer to interface object.
//   
//    pKeyName -
//       Pointer to NULL terminated string that contains the
//       name of the key whose value is being requested.
//               
// Returns:
//    Pointer to NULL terminated string with value being requested or NULL.
//                           
// Description:
//    Gets value associated with a key for the configuration object.
//=======================================================================--


//
// Config Interface Object
// 
typedef struct _ConfigIf
{
   PFN_AddReference                    addReference;
   PFN_ReleaseReference                releaseReference;
   PFN_GetEntryValue                   getEntryValue;

} ConfigIf, *PConfigIf;



/**************************************************************************
***************************************************************************
**                                                                       **
**    Authentication Token Interface Definitions                         **
**                                                                       **
***************************************************************************
**************************************************************************/


//++=======================================================================
typedef
CasaStatus 
(SSCS_CALL *PFN_GetAuthTokenCredentials)(
   IN       const void        *pIfInstance,
   IN       const ConfigIf    *pServiceConfigIf,
   INOUT    const char        *pUserNameBuf,
   INOUT    int               *pUserNameBufLen,
   INOUT    const char        *pTokenBuf,
   INOUT    int               *pTokenBufLen);
//
// Arguments:  
//    pIfInstance -
//       Pointer to interface object.
//   
//    pServiceConfigIf -
//       Pointer to service config object to which the client is trying to
//       authenticate.
//               
//    pUserNameBuf -
//       Pointer to buffer that will receive a string with the
//       username that should used when authenticating to the
//       service. The length of this buffer is specified by the
//       pUserNameBufLen parameter. Note that the string
//       returned will be NULL terminated.
//
//    pUserNameBufLen -
//       Pointer to integer that contains the length of the
//       buffer pointed at by pUserNameBuf. Upon return of the
//       function, the integer will contain the actual length
//       of the username string (including the NULL terminator)
//       if the function successfully completes or the buffer
//       length required if the function fails because the buffer
//       pointed at by either pUserNameBuf or pTokenBuf is not
//       large enough.
//               
//    pTokenBuf -
//       Pointer to buffer that will receive the authentication
//       token. The length of this buffer is specified by the
//       pTokenBufLen parameter. Note that the the authentication
//       token will be in the form of a NULL terminated string.
//
//    pTokenBufLen -
//       Pointer to integer that contains the length of the
//       buffer pointed at by pTokenBuf. Upon return of the
//       function, the integer will contain the actual length
//       of the authentication token if the function successfully
//       completes or the buffer length required if the function
//       fails because the buffer pointed at by either pUserNameBuf
//       or pTokenBuf is not large enough. Please note that the
//       authentication token
//   
// Returns:
//    Casa Status
//                           
// Description:
//    Get authentication token credentials to authenticate user to specified
//    service.
//=======================================================================--


//++=======================================================================
typedef
CasaStatus
(SSCS_CALL *PFN_ValidateAuthTokenCredentials)(
   IN       const void        *pIfInstance,
   IN       const ConfigIf    *pServiceConfigIf,
   IN       const char        *pUserName,
   IN       const int         userNameLen,
   IN       const char        *pTokenBuf,
   IN       const int         tokenBufLen);
//
// Arguments:  
//    pIfInstance -
//       Pointer to interface object.
//   
//    pServiceConfigIf -
//       Pointer to service config object to which the client is trying to
//       authenticate.
//               
//    pUserName -
//       Pointer to string with the username that is being
//       authenticated to the service. The length of the name
//       is specified by the pUserNameLen parameter. Note that
//       the string does not need to be NULL terminated.
//
//    userNameLen -
//       Length of the user name contained within the buffer
//       pointed at by pUserNameBuf (Does not include the NULL
//       terminator). If this parameter is set to -1 then the
//       function assumes that the username string is NULL
//       terminated.
//               
//    pTokenBuf -
//       Pointer to buffer that will receive the authentication
//       token. The length of this buffer is specified by the
//       pTokenBufLen parameter. Note that the the authentication
//       token will be in the form of a NULL terminated string.
//
//    tokenBufLen -
//       Length of the data contained within the buffer pointed
//       at by pTokenBuf.
//   
// Returns:
//    Casa status.
//                           
// Description:
//    Validates authentication token credentials.
//
//=======================================================================--


//
// AuthToken Interface Object
// 
typedef struct _AuthTokenIf
{
   PFN_AddReference                    addReference;
   PFN_ReleaseReference                releaseReference;
   PFN_GetAuthTokenCredentials         getAuthTokenCredentials;
   PFN_ValidateAuthTokenCredentials    validateAuthTokenCredentials;

} AuthTokenIf, *PAuthTokenIf;


//++=======================================================================
typedef
CasaStatus
(SSCS_CALL *PFN_GetAuthTokenIfRtn)(
   IN       const ConfigIf    *pModuleConfigIf,
   INOUT    AuthTokenIf       **ppAuthTokenIf);
//
// Arguments:  
//    pModuleConfigIf -
//       Pointer to configuration interface instance for the module.
//               
//    ppAuthTokenIf -
//       Pointer to variable that will receive pointer to AuthTokenIf
//       instance.
//
// Returns:
//    Casa Status
//                           
// Description:
//    Gets authentication token interface instance.
//=======================================================================--

#define GET_AUTH_TOKEN_INTERFACE_RTN_SYMBOL  "GetAuthTokenInterface"
#define GET_AUTH_TOKEN_INTERFACE_RTN         GetAuthTokenInterface


#if defined(__cplusplus) || defined(c_plusplus)
}
#endif // #if defined(__cplusplus) || defined(c_plusplus)

#endif // #ifndef _AUTH_TOKEN_INT_H_