/* @(#)49	1.4  src/security/idl/pklbase.idl, security.src, os2dce21.dss, 960602a.1 5/17/95 09:49:52 */
/*
 * COMPONENT_NAME:  security.client.src 
 *
 * FUNCTIONS: 
 *
 * ORIGINS: 72
 *
 */
/*
 * Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc.
 * ALL RIGHTS RESERVED (DCE).  See the file named COPYRIGHT.DCE in the
 * src directory for the full copyright text.
 */
/*
 * HISTORY
 * $Log: pklbase.idl,v $
 * Revision 1.1.2.2  1992/12/29  13:29:54  zeliff
 *      Embedding copyright notice
 *      [1992/12/28  20:16:59  zeliff]
 *
 * Revision 1.1  1992/01/19  14:55:16  devrcs
 * Initial revision
 *
 * $EndLog$
 */
/*
*/

/*  pklbase.idl V=1 08/08/91 //efferdent/d2/idl2
**
** Copyright (c) Hewlett-Packard Company 1991
** Unpublished work. All Rights Reserved.
**
*/
/*
**  Copyright (c) 1991 by
**      Hewlett-Packard Company, Palo Alto, Ca.
**
**   Copyright (c) Hewlett-Packard Company 1991
**   Unpublished work. All Rights Reserved.
**  
**
**  NAME:
**
**      pklbase.idl
**
**  FACILITY:
**
**      Pickling support
**
**  ABSTRACT:
**
**      base types and consts for pickle users
**
**  
**
*/

[
version(1.0)
]
interface pklbase
{

/*
 * I N T R O 
 *
 * For a given type T, there may a pair of (local) routines T_pickle
 * and T_unpickle.  T_pickle produces a pickled representation of a given
 * value of type T.  T_unpickle produces an instance of type T whose
 * value is encoded in a given pickle.  The purpose is permit typed values
 * to be stored (e.g. in simple data bases) and manipulated (e.g. by
 * encryption or compression) through generic (i.e. byte stream)
 * interfaces.  The signatures of these routines are:
 *
 * void T_pickle(
 *     [in]  T *data,                        /* pickle-ee 
 *     [in]  rpc_syntax_id_t syntax,         /* syntax to use,
 *                                              (syntax.id == uuid_nil) => unspec
 *     [in]  void *(*allocator)(unsigned32), /* allocator to allocate pickle
 *     [in]  unsigned32 alloc_mod,           /* (*pickle_len mod alloc_mod)
 *                                              should be 0
 *     [out] idl_pkl_t **pickle,             /* the resulting pickle
 *     [out] unsigned32 *pickle_len,         /* its length in bytes
 *     [out] error_status_t *st              /*
 * );
 *
 * void T_unpickle(
 *     [in]  idl_pkl_t *pickle,              /* unpickle-ee
 *     [in]  void *(*allocator)(unsigned32), /* allocator to allocate memory
 *                                              pointed at by *data  
 *     [out] T *data,                        /* object of type T to receive
 *                                              value from *pickle
 *     [out] error_status_t *st              /*
 * );
 *
 */


/*
 * i d l _ p k l _ t
 *
 * A pickle is the representation in a byte stream of a value whose type
 * is specified in IDL.  A pickle is divided into two parts: a "header"
 * part followed by a "data" part.
 *
 * The header part contains four fields encoded according to the spec
 * given below: an rpc_syntax_id_t specifying the encoding used in the
 * pickle, a uuid_t specifying the type of the value encoded in the pickle,
 * an unsigned small (8 bit) pickle header version number (0 for this
 * version), and a 24 bit unsigned integer giving the length in bytes
 * of the data part of the pickle.
 *
 * The size of the header part of a pickle in 40 bytes.  For applications
 * that need to access the data part of a pickle the constant
 * idl_pkl_data_offset is defined.
 *
 * The data part of a pickle is a byte stream that contains the encoding
 * of the value per the encoding syntax specified in the header; this may
 * include some info that is needed by the selected syntax and properly
 * part of the pickled value (e.g. the NDR format label).
 *
 * Assuming that the info in a pickle header could be modeled by the
 * following type
 *
 *      struct idl_pkl_header_t {
 *          unsigned8 version;      /* pickle header version 
 *          unsigned8 length_hi;    /* len of data part (hi byte)
 *          unsigned16 length_low;  /* len of data part (low bytes)
 *          rpc_syntax_id_t syntax; /* encoding syntax used
 *          uuid_t type;            /* id of type encoded 
 *      } idl_pkl_header_t;
 *
 * here is the layout of the pickle header (all integers are encoded
 * in big-endian form):
 *
 *      name                                type        offset(s)
 *      ----                                ----        ---------
 *      version                             unsigned8   0
 *      length_hi                           unsigned8   1
 *      length_low                          unsigned16  2,3
 *      syntax.id.time_low                  unsigned32  4,5,6,7
 *      syntax.id.time_mid                  unsigned16  8,9
 *      syntax.id.time_hi_and_version       unsigned16  10,11
 *      syntax.id.clock_seq_hi_and_reserved unsigned8   12
 *      syntax.id.clock_seq_low             unsigned8   13
 *      syntax.id.node[0]                   byte        14
 *      syntax.id.node[1]                   byte        15
 *      syntax.id.node[2]                   byte        16
 *      syntax.id.node[3]                   byte        17
 *      syntax.id.node[4]                   byte        18
 *      syntax.id.node[5]                   byte        19
 *      syntax.version                      unsigned32  20,21,22,23
 *      type.id.time_low                    unsigned32  24,25,26,27
 *      type.id.time_mid                    unsigned16  28,29
 *      type.id.time_hi_and_version         unsigned16  30,31
 *      type.id.clock_seq_hi_and_reserved   unsigned8   32
 *      type.id.clock_seq_low               unsigned8   33
 *      type.id.node[0]                     byte        34  
 *      type.id.node[1]                     byte        35  
 *      type.id.node[2]                     byte        36  
 *      type.id.node[3]                     byte        37  
 *      type.id.node[4]                     byte        38  
 *      type.id.node[5]                     byte        39  
 *
 */
typedef byte idl_pkl_t[];

const unsigned long idl_pkl_data_offset = 40;

}
