/***********************************************************************
 * 
 *  Copyright (C) 2006 Novell, Inc. All Rights Reserved.
 *
 *  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 Lesser 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, Novell, Inc.
 * 
 *  To contact Novell about this file by physical or electronic mail, 
 *  you may find current contact information at www.novell.com.
 * 
 *  Author: Juan Carlos Luciani <jluciani@novell.com>
 *
 ***********************************************************************/

#ifndef _IDEN_TOKEN_PROVIDER_IF_H_
#define _IDEN_TOKEN_PROVIDER_IF_H_


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

#include "config_if.h"

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

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

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


/**************************************************************************
***************************************************************************
**                                                                       **
**    Identity Token Interface Definitions                               **
**                                                                       **
***************************************************************************
**************************************************************************/


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


//++=======================================================================
typedef
void       
(SSCS_CALL *PFNIdenTokenIf_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.
//=======================================================================--


//++=======================================================================
typedef
CasaStatus 
(SSCS_CALL *PFNIdenTokenIf_GetIdentityId)(
   IN       const void  *pIfInstance,
   INOUT    char        *pIdentIdBuf,
   INOUT    size_t      *pIdentIdLen);
//
// Arguments:  
//    pIfInstance -
//       Pointer to interface object.
//   
//    pIdentIdBuf -
//       Pointer to buffer that will receive the identity id. The returned
//       id will be in the form of a NULL terminated string.
//
//    pIdentIdBufLen -
//       Pointer to variable with the length of the buffer pointed by
//       pIdentIdBuf. On exit it contains the length of the returned id
//       (including the NULL terminator).
//
//   
// Returns:
//    Casa Status
//                           
// Description:
//    Get the identity id associated with the identity token.
//=======================================================================--


//++=======================================================================
typedef
CasaStatus 
(SSCS_CALL *PFNIdenTokenIf_GetSourceName)(
   IN       const void  *pIfInstance,
   INOUT    char        *pSourceNameBuf,
   INOUT    size_t      *pSourceNameLen);
//
// Arguments:  
//    pIfInstance -
//       Pointer to interface object.
//   
//    pSourceNameBuf -
//       Pointer to buffer that will receive the name associated with the
//       identity information source. The returned name will be in the form
//       of a NULL terminated string.
//
//    pSourceNameBufLen -
//       Pointer to variable with the length of the buffer pointed by
//       pSourceNameBuf. On exit it contains the length of the returned
//       name (including the NULL terminator).
//
//   
// Returns:
//    Casa Status
//                           
// Description:
//    Get the name of the identity source associated with the identity token.
//=======================================================================--


//++=======================================================================
typedef
CasaStatus 
(SSCS_CALL *PFNIdenTokenIf_GetSourceUrl)(
   IN       const void  *pIfInstance,
   INOUT    char        *pSourceUrlBuf,
   INOUT    size_t      *pSourceUrlLen);
//
// Arguments:  
//    pIfInstance -
//       Pointer to interface object.
//   
//    pSourceUrlBuf -
//       Pointer to buffer that will receive the URL associated with the
//       identity information source. The returned URL will be in the form
//       of a NULL terminated string.
//
//    pSourceUrlBufLen -
//       Pointer to variable with the length of the buffer pointed by
//       pSourceUrlBuf. On exit it contains the length of the returned
//       URL (including the NULL terminator).
//
//   
// Returns:
//    Casa Status
//                           
// Description:
//    Get the URL to the identity source associated with the identity token.
//=======================================================================--


//++=======================================================================
typedef
CasaStatus 
(SSCS_CALL *PFNIdenTokenIf_AttributeEnumerate)(
   IN       const void     *pIfInstance,
   INOUT    unsigned int   *pEnumHandle,       
   INOUT    char           *pAttribNameBuf,
   INOUT    size_t         *pAttribNameLen,
   INOUT    char           *pAttribValueBuf,
   INOUT    size_t         *pAttribValueLen);
//
// Arguments:  
//    pIfInstance -
//       Pointer to interface object.
//   
//    pEnumHandle -
//       Pointer to enumeration handle. Must be set to 0 to start an
//       enumeration. Note the enumeration handle advances if the
//       function returns success.
//
//    pAttribNameBuf -
//       Pointer to buffer that will receive the identity attribute name. The
//       returned name will be in the form of a NULL terminated string.
//
//    pAttribNameLen -
//       Pointer to variable with the length of the buffer pointed by
//       pAttribNameBuf. On exit it contains the length of the returned
//       name (including the NULL terminator).
//
//    pAttribValueBuf -
//       Pointer to buffer that will receive the identity attribute value. The
//       returned value will be in the form of a NULL terminated string.
//
//    pAttribValueLen -
//       Pointer to variable with the length of the buffer pointed by
//       pAttribValueBuf. On exit it contains the length of the returned
//       value (including the NULL terminator).
//
//   
// Returns:
//    Casa Status
//                           
// Description:
//    Enumerates through the attributes associated with the identity token.
//=======================================================================--


//
// Identity Token Interface Object
// 
typedef struct _IdenTokenIf
{
   PFNIdenTokenIf_AddReference         addReference;
   PFNIdenTokenIf_ReleaseReference     releaseReference;
   PFNIdenTokenIf_GetIdentityId        getIdentityId;
   PFNIdenTokenIf_GetSourceName        getSourceName;
   PFNIdenTokenIf_GetSourceUrl         getSourceUrl;
   PFNIdenTokenIf_AttributeEnumerate   attributeEnumerate;

} IdenTokenIf, *PIdenTokenIf;


/**************************************************************************
***************************************************************************
**                                                                       **
**    Identity Token Provider Interface Definitions                      **
**                                                                       **
***************************************************************************
**************************************************************************/


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


//++=======================================================================
typedef
void       
(SSCS_CALL *PFNIdenTokenProviderIf_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.
//=======================================================================--


//++=======================================================================
typedef
CasaStatus 
(SSCS_CALL *PFNIdenTokenProviderIf_GetIdentityTokenIf)(
   IN       const void        *pIfInstance,
   IN       const char        *pTokenBuf,
   IN       const size_t      tokenLen,
   INOUT    IdenTokenIf       **ppIdenTokenIf);
//
// Arguments:  
//    pIfInstance -
//       Pointer to interface object.
//   
//    pTokenBuf -
//       Pointer to null terminated string containing an identity token.
//
//    tokenLen -
//       Length of the token contained in the token buffer.
//
//    ppIdenTokenIf -
//       Pointer to variable that will receive pointer to identity
//       token interface.
//   
// Returns:
//    Casa Status
//                           
// Description:
//    Get identity token interface instance for the specified token.
//=======================================================================--


//
// Identity Token Provider Interface Object
// 
typedef struct _IdenTokenProviderIf
{
   PFNIdenTokenProviderIf_AddReference          addReference;
   PFNIdenTokenProviderIf_ReleaseReference      releaseReference;
   PFNIdenTokenProviderIf_GetIdentityTokenIf    getIdentityTokenIf;

} IdenTokenProviderIf, *PIdenTokenProviderIf;


//++=======================================================================
typedef
CasaStatus
(SSCS_CALL *PFN_GetIdenTokenProviderIfRtn)(
   IN       const ConfigIf       *pModuleConfigIf,
   INOUT    IdenTokenProviderIf  **ppIdenTokenProviderIf);
//
// Arguments:  
//    pModuleConfigIf -
//       Pointer to configuration interface instance for the module.
//               
//    ppIdenTokenProviderIf -
//       Pointer to variable that will receive pointer to
//       IdentityTokenProviderIf instance.
//
// Returns:
//    Casa Status
//                           
// Description:
//    Gets identity token provider interface instance.
//=======================================================================--

#define GET_IDEN_TOKEN_PROVIDER_INTERFACE_RTN_SYMBOL  "GetIdenTokenProviderInterface"
#define GET_IDEN_TOKEN_PROVIDER_INTERFACE_RTN         GetIdenTokenProviderInterface


#endif // #ifndef _IDEN_TOKEN_PROVIDER_IF_H_