/*
**
**  $Id: rwkss.h,v 1.17 2000/08/31 02:42:15 slin Exp $
**
**  Copyright (c) 1998 by Oracle Corporation. All rights reserved. 
**    NAME
**      rwkss.h
**    DESCRIPTION
**      Reports Server Security Service -- header file for rwkss.c
**      
**    NOTES
**      
**    MODIFIED   (MM/DD/YY)
**     Jeff Tang(jitang) 10/27/98 created
*/

#ifndef RWKSS
#define RWKSS

#ifndef S
# include <s.h>
#endif

#ifndef CA
# include <ca.h>
#endif

#ifndef LX
# include <lx.h>
#endif

#ifndef RWN
# include <rwn.h>
#endif

#ifndef LDX
# include <ldx.h>
#endif

#ifndef ZRCCT
# include <zrcct.h>
#endif

/* C++ compatibility */
#ifdef __cplusplus
extern "C"
{
#endif

#define USERID (text*)"userid"
#define AUTHID (text*)"authid"

#define MAX_NAMELEN 128
#define MAX_VALUELEN 1024

/* retry times if last OCI or RWN call failed */
#define RWKSS_RETRY_TIMES    1

/* WebDB security setting preference name */
#define RWKSS_PREF_DOMAIN    "P_DOMAIN"

/*
 |
 | E R R O R    C O D E S
 |
 */
#define RWKSS_ERRID_BASE             (caxstatus)0

#define RWKSS_ERRID_NOERROR          ((caxstatus)(RWKSS_ERRID_BASE))
#define RWKSS_ERRID_NOMEMORY         ((caxstatus)(RWKSS_ERRID_BASE+1))
#define RWKSS_ERRID_REQATTR          ((caxstatus)(RWKSS_ERRID_BASE+2))
#define RWKSS_ERRID_OCIINIT_FAILED   ((caxstatus)(RWKSS_ERRID_BASE+3))
#define RWKSS_ERRID_NOSUCHUSER       ((caxstatus)(RWKSS_ERRID_BASE+4))
#define RWKSS_ERRID_AUTHFAILED       ((caxstatus)(RWKSS_ERRID_BASE+5))
#define RWKSS_ERRID_BADPARAM         ((caxstatus)(RWKSS_ERRID_BASE+6))
#define RWKSS_ERRID_INVALIDUSERID    ((caxstatus)(RWKSS_ERRID_BASE+7))
#define RWKSS_ERRID_WEBDBERR         ((caxstatus)(RWKSS_ERRID_BASE+8))

/*
 * M A S K    B I T S 
 */
#define RWKSS_MASK_LANGID        ((ub2)1 << 0)  /* lang id */
#define RWKSS_MASK_LAGLOB        ((ub2)1 << 1)  /* lang globe object */
#define RWKSS_MASK_TNSNAME       ((ub2)1 << 2)  /* security db tnsname */
#define RWKSS_MASK_PORTALUSERID  ((ub2)1 << 4)  /* security db userid */

/*
 |
 |  O P A Q U E   O B J E C T   D E F I N I T I O N
 |
 */
typedef dvoid *rwkss_system; /* system object */

typedef dvoid *rwkss_user; /* user(session) object */

typedef dvoid *rwkss_job; /* scheduled job object */

/*
 |
 |  P U B L I C   O B J E C T   D E F I N I T I O N
 |
 */
typedef enum{
  HTML,
  HTMLCSS,
  PDF,
  POSTSCRIPT,
  RTF,
  USASCII,
  GIF
}rwkss_fileformat;

typedef struct rwkss_cmdargument{
  text name[MAX_NAMELEN];
  text value[MAX_VALUELEN];
}rwkss_cmdargument;

typedef struct rwkss_system_attribute{
  cax *ctx;                  /* CA context */
  lx_langid langid;          /* lang id */
  lxglo *lxglob;             /* lang globe object */
  text *tnsname;             /* security database tnsname */
  ub2 mask;                  /* mask */
  text *defaultuserid;       /* security database default userid */  
} rwkss_system_attribute;

typedef struct rwkss_scheduleinfo{
  ldxg timelastrun;         /* time stamp when job last ran */
  ldxg timenextrun;         /* time scheduled to run next */
  zrcct_repintv repintvval; /* repeat time interval */
}rwkss_scheduleinfo;

/*--------------------------------------------------------------------*/
/*                                                                    */
/*                      Security    System     Services               */
/*                                                                    */
/*--------------------------------------------------------------------*/
/* 
 * This function initializes the security system. It calls rwn OCI init 
 * functions and save the rwnp_ctxt object for future usage. Clients
 * call this function to start up the security system. For Reports Server,
 * this function will be called during Reports Server start up process
 * if system security tnsname is set in the server configuration file.
 * After creating the system object, client should call 
 * rwkss_SetSystemAttribute to setup system attributes.
 * 
 * caxstatus rwkss_CreateSecuritySystem(ctx, webdb_tnsname, system_ctx)
 *
 * Parameter: webdb      -- webdb tnsname
 *            system_ctx -- security system object created by this function
 *            att        -- security system attributes
 * Return Value: caxstatus -- error code.
 */
caxstatus rwkss_CreateSecuritySystem(/*_
  cax *ctx, 
  rwkss_system *system_ctx,   
  rwkss_system_attribute *att
_*/);

/* 
 * This function cleans up the security system and deletes the sysctx object.
 * All underlying OCI connections and user sessions are all destroyed. 
 * The rwswk_system system object will be freed. It also removes all 
 * rwswk_user objects and rwswk_job objects.
 * 
 * caxstatus rwkss_DeleteSecuritySystem(system_ctx)
 *
 * Parameter: sysctx -- security system object
 *
 * Return Value: caxstatus -- error code.
 */
caxstatus rwkss_DestroySecuritySystem(/*_ rwkss_system system_ctx _*/);

/*
 * This functions sets different attributes of security system object. 
 * Clients can call this function to set/reset attributes by setting the 
 * mask and providing the correct value.
 *
 * caxstatus rwkss_SetAttribute(system_ctx, att)
 *
 * Parameter: system_ctx -- security system object
 *            att -- new system attribute
 *
 * Return Value: caxstatus -- error code.
 */
caxstatus rwkss_SetSystemAttribute(/*_
  rwkss_system system_ctx,  
  rwkss_system_attribute *att
_*/);

/*
 * Connect to the security system database
 */
caxstatus rwkss_Connect(/*_
  rwkss_system  system_ctx
_*/);

/* 
 * This function gets the server preference from WebView security preference 
 * settings. Reports server should call this function *AFTER* it has 
 * establised at least one user session.
 *
 * caxstatus rwkss_GetSecurityPreference(system_ctx, userctx, preference_name, 
                                         preference_value)
 *
 * Parameters: system_ctx -- security system object
 *             userctx -- user object.
 *             preference_name -- indicate the preference will be retrieved.
 *             preference_value -- the preference value returned.
 *
 * Return Value: caxstatus -- error code.
 */
caxstatus rwkss_GetSecurityPreference(/*_
  rwkss_system system_ctx,
  rwkss_user user, 
  text *preference_name, 
  text *preference_value  
_*/);

/* 
 * This function returns the error message of previous RWK function call.
 * Caller doesn't need to allocate buffer for error message, nor should free
 * it.
 *
 * caxstatus rwkss_GetErrorMsg(system_ctx, errmsg)
 *
 * Parameters: system_ctx -- security system object
 *             errmsg - error message
 *
 * Return Value: caxstatus -- error code.
 */
caxstatus rwkss_GetErrorMsg(/*_
  rwkss_system system_ctx,
  text **errmsg
_*/);

/*--------------------------------------------------------------------*/
/*                                                                    */
/*                       User(session) functions                      */
/*                                                                    */
/*--------------------------------------------------------------------*/
/* 
 * This function authenticates user by passing in user name, password and 
 * the database(tnsname) user wants to connect to. If the authentication is
 * successful, the created user object will be returned. 
 *
 * caxstatus rwkss_AuthenticateUser(system_ctx, username, 
 *                                  password, tnsname, userctx)
 *
 * Parameters: system_ctx -- security system object.
 *             user name --   user name
 *             password  --   password.
 *             tnsname   --   database tnsname
 *             userctx   --   the created rwkss_user object. 
 *
 * Return Value:  caxstatus -- access check result
 */
caxstatus rwkss_AuthenticateUser(/*_
  rwkss_system system_ctx,
  text *username,
  text *password,
  text *tnsname,
  rwkss_user *userctx  
_*/);

/* 
 * This function authenticates a system user by passing in user name and 
 * the password. If the authentication is successful, the created user 
 * object will be returned. 
 *
 * caxstatus rwkss_AuthenticateUser(system_ctx, username, 
 *                                  password, tnsname, userctx)
 *
 * Parameters: system_ctx -- security system object.
 *             user name --   user name
 *             password  --   password.
 *             userctx   --   the created rwkss_user object. 
 *
 * Return Value:  caxstatus -- access check result
 */

caxstatus rwkss_AuthenticateSystemUser(/*_
  rwkss_system system_ctx,
  text *username,
  text *password,
  rwkss_user *userctx  
_*/);

/* 
 * This function logoff user. The database session for this user will also 
 * be closed.
 *
 * caxstatus rwkss_LogoffUser(system_ctx, userctx)
 *
 * Parameters: system_ctx -- security system object.
 *             userctx -- user object
 *
 * Return Value: caxstatus -- error code.
 */
caxstatus rwkss_LogoffUser(/*_
  rwkss_system system_ctx, 
  rwkss_user userctx
_*/);

/* 
 * This function validates a user session by passing in the sessionid and 
 * the database(tnsname) user wants to connect to. If the validation is
 * successful, the created user object will be returned. 
 *
 * caxstatus rwkss_ValidateSession(system_ctx, sessionid, tnsname, userctx)
 *
 * Parameters: system_ctx -- security system object.
 *             sessionid  -- security session identifier 
 *             username   -- username 
 *             userctx    --   the created rwkss_user object. 
 *
 * Return Value: caxstatus -- error code.
 */
caxstatus rwkss_ValidateSession(/*_
  rwkss_system system_ctx,
  text *sessionid,
  text *username,
  rwkss_user *userctx 
_*/);

/* 
 * This function gets user object by passing in user name, password.
 * Return NULL if not found.
 *
 * caxstatus rwkss_GetUserObject(system_ctx, username, password, userctx)
 *
 * Parameters: system_ctx -- security system object.
 *             user name  --   user name
 *             password   --   password.
 *             userctx    --   the created rwkss_user object. 
 *
 * Return Value: caxstatus -- error code.
 */
caxstatus rwkss_GetUserObject(/*_
  rwkss_system system_ctx,
  text        *username,
  text        *password,
  rwkss_user  *userctx 
_*/);

/* 
 * This function checks user accessibility by calling security system
 * functions(WebDB procedures).
 *
 * caxstatus rwkss_SecurityCheck(userctx, arglist, arglistsize)
 * 
 * Parameters: system_ctx -- security system object.
 *             userctx -- user object
 *             arglist -- an array of CmdArgument structure, it contains the 
 *                        name/value pair for all parameters, including 
 *                        destype, desformat and user defined arguments, etc. 
 *             arglistsize -- size of argnamelist
 *             time   -- time to run the report
 *
 * Return Value:  caxstatus -- access check result
 *
 */
caxstatus rwkss_SecurityCheck(/*_
  rwkss_system system_ctx,
  rwkss_user userctx,
  rwkss_cmdargument *arglist, 
  ub4  arglistsize,
  ldxg *time
_*/);

/* 
 * This function returns rdf file name based on module name.
 * caxstatus rwkss_GetRdfFileName(system_ctx, userctx, modulename, filename)
 * 
 * Parameters: system_ctx  -- security system object.
 *             userctx     -- user object
 *             modulename  -- WebDB module name
 *             rdffilename -- report RDF file name, IN/OUT 
 *
 * Return Value: caxstatus -- error code.
 */
caxstatus rwkss_GetRdfFileName(/*_
  rwkss_system system_ctx,
  rwkss_user user_ctx,
  text *modulename,
  text *rdffilename 
_*/);

/* 
 * This function checks if the user has the priviledge to execute certain
 * URL command, e.g., showjobs, showenv, or showmap, etc.
 * 
 * Parameters: system_ctx  -- security system object.
 *             userctx     -- user object
 *             command     -- URL command, like 'showjobs' or 'showenv'
 *
 * Return Value: caxstatus -- error code.
 */
caxstatus rwkss_CheckCommand(/*_
  rwkss_system system_ctx,
  rwkss_user user_ctx,
  text *command
_*/);

/* 
 * This funtion returns the role information for the user.
 * 
 * Parameters: system_ctx  -- security system object.
 *             userctx     -- user object
 *             role        -- OUT: role info returned to caller.
 *
 * Return Value: caxstatus -- error code.
 */
caxstatus rwkss_GetRole(/*_
  rwkss_system system_ctx,
  rwkss_user user_ctx,
  ub2 *role
_*/);

/* 
 * This function sends log info into webdb if the command line contains
 * _wwv_rw_log_id_ and _wwv_rw_stime_ arguments
 * 
 * Parameters: system_ctx  -- security system object.
 *             user_ctx    -- user object
 *             arglist     -- argument list
 *             arglistsize -- number of argument
 *
 * Return Value: caxstatus -- error code.
 */
caxstatus rwksswl_WebDBLog(/*_
  rwkss_system        system_ctx,
  rwkss_user          user_ctx,
  rwkss_cmdargument  *arglist, 
  ub4                 arglistsize
_*/);


/*--------------------------------------------------------------------*/
/*                                                                    */
/*                      Job Scheduling Functions                      */
/*                                                                    */
/*--------------------------------------------------------------------*/
/* 
 *  Creates a link to webdb for the scheduled job.  A folder will be
 *    created on the webdb.  The site and folder name are specified in
 *    the arglist.  A job context will be returned from this function.
 *
 *  Parameters:
 *    sysctx        - input, a valid rwkss_system context
 *    user_ctx      - input, a vlid rwkss_user context
 *    arglist       - input, a list of paired command line argments
 *    arglistsize   - input, size of the arglist (number of elements)
 *    scheduleinfo  - input, filled scheduleinfo record
 *    jobid         - input, the id of the job in the Report Server
 *    job           - output, allocated by this function, a job context
 */
caxstatus rwkss_CreateScheduledJob(/*_
  rwkss_system        sysctx, 
  rwkss_user          user_ctx,
  rwkss_cmdargument  *arglist, 
  ub4                 arglistsize,
  rwkss_scheduleinfo *scheduleinfo,
  zrcct_jobid         jobid,
  rwkss_job          *job  
_*/);

/* 
 *  Deletes the job context and removes the link to the webdb
 *    The webdb site associated with this job will be updated to reflect
 *    that this job has been cancelled
 *
 *  Parameter:
 *    jobctx        - input, a valid job context
 */
caxstatus rwkss_DeleteScheduledJob(/*_
  rwkss_job jobctx
_*/);

/* 
 *  Sends the file to the webdb.  If the output is html, then the index
 *    file is sent with this function.  For additional files, use the
 *    PutJobOutputFile call.
 *
 *  Parameters:
 *    jobctx        - input, a valid job context
 *    status        - input, indicates success or failure
 *    date          - input, current time
 *    filename      - input, name of the file
 *    mime_type     - input, mime type of the file
 */
caxstatus rwkss_AddJobLogfile(/*_
  rwkss_job jobctx, 
  boolean status, 
  ldxg *date, 
  text *filename,
  text *mime_type
_*/);

/* 
 *  Sends the file to the webdb.  Use this function to send children
 *    of the first file.  Primarily used for html files.
 *
 *  Parameters:
 *    jobctx        - input, a valid job context
 *    filename      - input, name of the file
 *    mime_type     - input, mime type of the file
 */
caxstatus rwkss_PutJobOutputFile(/*_
  rwkss_job jobctx, 
  text *filename, 
  text *mime_type
_*/);

/* 
 *  Update the job status on the webdb.
 *
 *  Parameters:
 *    jobctx        - input, a valid job context
 *    reportObjId   - input, the report job id
 *    timelastrun   - input, time the job was last run
 *    timenextrun   - input, time the job is scheduled to run
 */
caxstatus rwkss_AddJobStatus(/*_
  rwkss_job jobctx,
  size_t reportObjId, 
  ldxg *timelastrun, 
  ldxg *timenextrun
_*/);

/* 
 *  Writes out the job context into a block of memory, or in other words,
 *    serialize the job context
 *
 *  Parameters:
 *    jobctx        - input, a valid job context
 *    buffer        - input/output, allocated by client and job context
 *                    is written into this buffer
 *    bytesWritten  - output, returns number of bytes written
 */
caxstatus rwkss_WriteContext(/*_
  rwkss_job jobctx,
  text  *buffer,
  ub4   *bytesWritten
_*/);

/* 
 *  Rebuilds the job context from a persistent storage.  However, 
 *    the caller needs to call rwkss_RestoreContext to completely
 *    rebuild the job context.
 *
 *  Parameters:
 *    cactx         - input, a valid cax context
 *    langid        - input, a valid language id
 *    lxglo         - input, a valid lx global pointer
 *    buffer        - input, points to the data
 *    jobctx        - output, allocated by this function
 *    bytesRead     - output, returns number of bytes read from the buffer
 */
caxstatus rwkss_ReadContext(/*_
  cax       *cactx,
  lx_langid langid,
  lxglo     *lxglob,
  text      *buffer,
  rwkss_job *jobctx,
  ub4       *bytesRead
_*/);

/* 
 *  Restores or refresh the rwkss_system and rwkss_user inside the job context
 *    Used in conjunction with rwkss_ReadContext to restore a job context
 *    from a persistent storage.
 *
 *  Parameters:
 *    jobctx        - input, allocated by rwkss_ReadContext
 *    sysctx        - input, a valid rwkss_system context
 *    user_ctx      - input, a valid rwkss_user context
 */
caxstatus rwkss_RestoreContext(/*_
  rwkss_job jobctx,
  rwkss_system   sysctx, 
  rwkss_user     user_ctx
_*/);

/* 
 *  Retrieve the amount of memory needed for rwkss_WriteContext
 *    Used by the client to allocate memory before calling WriteContext
 *
 *  Parameters:
 *    jobctx        - input, a valid job context
 */
ub4 rwkss_GetContextSize(/*_
  rwkss_job jobctx
_*/);


/* end of C++ compatibility */
#ifdef __cplusplus
}
#endif

#endif  /* RWKSS.H */