1/* 2 * Copyright (c) 2010 Apple Inc. All rights reserved. 3 * 4 * @APPLE_LICENSE_HEADER_START@ 5 * 6 * Redistribution and use in source and binary forms, with or without 7 * modification, are permitted provided that the following conditions 8 * are met: 9 * 10 * 1. Redistributions of source code must retain the above copyright 11 * notice, this list of conditions and the following disclaimer. 12 * 2. Redistributions in binary form must reproduce the above copyright 13 * notice, this list of conditions and the following disclaimer in the 14 * documentation and/or other materials provided with the distribution. 15 * 3. Neither the name of Apple Inc. ("Apple") nor the names of its 16 * contributors may be used to endorse or promote products derived from 17 * this software without specific prior written permission. 18 * 19 * THIS SOFTWARE IS PROVIDED BY APPLE AND ITS CONTRIBUTORS "AS IS" AND ANY 20 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 21 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 22 * DISCLAIMED. IN NO EVENT SHALL APPLE OR ITS CONTRIBUTORS BE LIABLE FOR ANY 23 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 24 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 25 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 26 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 27 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 28 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29 * 30 * Portions of this software have been released under the following terms: 31 * 32 * (c) Copyright 1989-1993 OPEN SOFTWARE FOUNDATION, INC. 33 * (c) Copyright 1989-1993 HEWLETT-PACKARD COMPANY 34 * (c) Copyright 1989-1993 DIGITAL EQUIPMENT CORPORATION 35 * 36 * To anyone who acknowledges that this file is provided "AS IS" 37 * without any express or implied warranty: 38 * permission to use, copy, modify, and distribute this file for any 39 * purpose is hereby granted without fee, provided that the above 40 * copyright notices and this notice appears in all source code copies, 41 * and that none of the names of Open Software Foundation, Inc., Hewlett- 42 * Packard Company or Digital Equipment Corporation be used 43 * in advertising or publicity pertaining to distribution of the software 44 * without specific, written prior permission. Neither Open Software 45 * Foundation, Inc., Hewlett-Packard Company nor Digital 46 * Equipment Corporation makes any representations about the suitability 47 * of this software for any purpose. 48 * 49 * Copyright (c) 2007, Novell, Inc. All rights reserved. 50 * Redistribution and use in source and binary forms, with or without 51 * modification, are permitted provided that the following conditions 52 * are met: 53 * 54 * 1. Redistributions of source code must retain the above copyright 55 * notice, this list of conditions and the following disclaimer. 56 * 2. Redistributions in binary form must reproduce the above copyright 57 * notice, this list of conditions and the following disclaimer in the 58 * documentation and/or other materials provided with the distribution. 59 * 3. Neither the name of Novell Inc. nor the names of its contributors 60 * may be used to endorse or promote products derived from this 61 * this software without specific prior written permission. 62 * 63 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY 64 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 65 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 66 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY 67 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 68 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 69 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 70 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 71 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 72 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 73 * 74 * @APPLE_LICENSE_HEADER_END@ 75 */ 76 77/* 78** 79** NAME: 80** 81** idl_es.h 82** 83** FACILITY: 84** 85** Interface Definition Language (IDL) Compiler 86** 87** ABSTRACT: 88** 89** User routine protoypes for IDL encoding services 90** 91*/ 92 93#ifndef IDL_ES_H 94#define IDL_ES_H 1 95 96#include <dce/dce.h> 97#include <dce/rpc.h> 98 99/*****************************************************************************/ 100/* */ 101/* IDL encoding services */ 102/* */ 103/*****************************************************************************/ 104 105typedef struct idl_es_handle_s_t *idl_es_handle_t; 106 107/* 108** Data types for read/write/alloc routines that manage 109** incremental processing of the encoding. 110*/ 111 112#ifdef __cplusplus 113extern "C" { 114#endif /* __cplusplus */ 115 116typedef void (*idl_es_allocate_fn_t) ( 117 idl_void_p_t , /* [in,out] user state */ 118 idl_byte **, /* [out] Address of buffer */ 119 idl_ulong_int * /* [in,out] Requested Size/Size of buffer */ 120);/* Routine to allocate a buffer */ 121 122typedef void (*idl_es_write_fn_t) ( 123 idl_void_p_t , /* [in,out] user state */ 124 idl_byte *, /* [in] Encoded data */ 125 idl_ulong_int /* [in] Size of encoded data */ 126); /* Routine to write encoded data */ 127 128typedef void (*idl_es_read_fn_t) ( 129 idl_void_p_t , /* [in,out] user state */ 130 idl_byte **, /* [out] Data to be decoded */ 131 idl_ulong_int * /* [out] Size of buf */ 132); /* Routine to read encoded data */ 133 134/* 135** Provides an idl_es_handle_t which allows an encoding operation to be 136** performed in an incremental fashion similar to pipe processing. 137** Buffers areas are requested by the stubs via the allocate routine as 138** necessary and when filled, are provided to the application via a 139** call to the write routine. This routine is suitable for encodings 140** that can be incrementally processed by the applications such as when 141** they are written to a file. The application may invoke multiple 142** operations utilizing the same handle. 143*/ 144 145void idl_es_encode_incremental ( 146 idl_void_p_t , /* [in] user state */ 147 idl_es_allocate_fn_t , /* [in] alloc routine */ 148 idl_es_write_fn_t , /* [in] write routine */ 149 idl_es_handle_t *, /* [out] encoding handle */ 150 error_status_t * /* [out] status */ 151); 152 153/* 154** Provides an idl_es_handle_t which allows an encoding operation to be 155** performed into a buffer provided by the application. If the buffer 156** is not of sufficient size to receive the encoding the error 157** rpc_s_no_memory is reported. This mechanism provides a simple, but 158** high performance encoding mechanism provided that the upper limit of 159** the encoding size is known. The application may invoke multiple 160** operation utilizing the same handle. 161*/ 162void idl_es_encode_fixed_buffer ( 163 idl_byte *, /* [in] pointer to buffer to */ 164 /* receive the encoding (must */ 165 /* be 8-byte aligned). */ 166 idl_ulong_int , /* [in] size of buffer provided */ 167 idl_ulong_int *, /* [out] size of the resulting */ 168 /* encoding (set after */ 169 /* execution of the stub) */ 170 idl_es_handle_t *, /* [out] encoding handle */ 171 error_status_t * /* [out] status */ 172); 173 174/* 175** Provides and idl_es_handle_t which provides an encoding in a 176** stub-allocated buffer. Although this mechanism provides the 177** simplest application interface, large encodings may incur a 178** performance penalty for this convenience. The return buffer is 179** allocated via the client memory allocation mechanism currently in 180** effect at the time of the encoding call. 181*/ 182void idl_es_encode_dyn_buffer ( 183 idl_byte **, /* [out] pointer to recieve the */ 184 /* dynamically allocated buffer */ 185 /* which contains the encoding */ 186 idl_ulong_int *, /* [out] size of the resulting */ 187 /* encoding (set after */ 188 /* execution of the stub) */ 189 idl_es_handle_t *, /* [out] decoding handle */ 190 error_status_t * /* [out] status */ 191); 192 193/* 194** Provides an idl_es_handle_t which allows an decoding operation to 195** be performed in an incremental fashion similar to pipe processing. 196** Buffers containing portions of the encoding are provided by the 197** application via calls to the read routine. This routine is 198** suitable for encodings that can be incremental decoded by the 199** stubs such as when they are read from a file. 200*/ 201void idl_es_decode_incremental ( 202 idl_void_p_t , /* [in] user state */ 203 idl_es_read_fn_t , /* [in] routine to supply buffers */ 204 idl_es_handle_t *, /* [out] decoding handle */ 205 error_status_t * /* [out] status */ 206); 207 208/* 209** Provides an idl_es_handle_t which allows an decoding operation to 210** be performed from a buffer containing the encoded data. There may 211** be a performance penalty if the buffer provided is not 8-byte 212** aligned. 213*/ 214void idl_es_decode_buffer ( 215 idl_byte *, /* [in] pointer to buffer */ 216 /* containing the encoding */ 217 idl_ulong_int , /* [in] size of buffer provided */ 218 idl_es_handle_t *, /* [out] decoding handle */ 219 error_status_t * /* [out] status */ 220); 221 222/* 223** Returns the rpc_if_id_t and operation number contained within the 224** encoding associated with an idl_es_handle_t. This information is 225** available during a decode operation, and after the operation has 226** been invoked for an encode operations. If this information is not 227** available, the status rpc_s_unknown_if is returned. 228*/ 229void idl_es_inq_encoding_id ( 230 idl_es_handle_t , /* [in] decoding handle */ 231 rpc_if_id_t *, /* [out] RPC interface */ 232 /* identifier (including */ 233 /* version information) */ 234 idl_ulong_int *, /* [out] operation number */ 235 error_status_t * /* [out] status */ 236); 237 238/* 239** Frees a idl_es_handle_t and its associated resources 240*/ 241void idl_es_handle_free ( 242 idl_es_handle_t *, /* [in,out] handle to free */ 243 error_status_t * /* [out] status */ 244); 245 246/* 247 * Machinery for stubs which support encodings in more than one transfer 248 * syntax 249 */ 250typedef enum { 251 idl_es_transfer_syntax_ndr 252}idl_es_transfer_syntax_t; 253 254void idl_es_set_transfer_syntax ( 255 idl_es_handle_t , 256 idl_es_transfer_syntax_t , 257 error_status_t * 258); 259 260/* 261 * Routines for getting and setting the attribute flag. 262 * 263 * Flags: 264 * IDL_ES_NO_ENCODING_CHECK This tells the encoding services to not 265 * check the interface id so an interface that 266 * did not encode data can decode parts of it 267 * (such as a common header). 268 */ 269 270#define IDL_ES_NO_ENCODING_CHECK 0x1 271 272/* 273 * Flags: 274 * IDL_ES_MIDL_COMPAT Compat with Microsoft Encoding Services 275 */ 276#define IDL_ES_MIDL_COMPAT 0x2 277 278/* 279 * Flags: 280 * IDL_ES_NO_HEADER No header (e.g. embedded in LDAP values) 281 */ 282#define IDL_ES_NO_HEADER 0x4 283 284void idl_es_set_attrs( 285 idl_es_handle_t, /* [in] handle */ 286 unsigned32, /* [in] flags */ 287 error_status_t *); /* [out] status */ 288 289void idl_es_inq_attrs( 290 idl_es_handle_t, /* [in] handle */ 291 unsigned32 *, /* [out] flags */ 292 error_status_t *); /* [out] status */ 293 294#ifdef __cplusplus 295} 296#endif /* __cplusplus */ 297 298#endif /* IDL_ES_H */ 299