/* begincopyright
  Copyright (c) 1988 Xerox Corporation. All rights reserved.
  Use and copying of this software and preparation of derivative works based
  upon this software are permitted. Any distribution of this software or
  derivative works must comply with all applicable United States export
  control laws. This software is made available AS IS, and Xerox Corporation
  makes no warranty about the software, its performance or its conformity to
  any specification. Any person obtaining a copy of this software is requested
  to send their name and post office or electronic mail address to:
    PCR Coordinator
    Xerox PARC
    3333 Coyote Hill Rd.
    Palo Alto, CA 94304
  endcopyright */

/*
 * ADotOutExtrasAccess.h
 *
 * PCR a.out extra section / subsections facility ...
 *
 * Demers, October 22, 1990 4:54:57 pm PDT
 */

#ifndef __ADotOutExtrasAccess__
#define __ADotOutExtrasAccess__	1

#ifndef __BasicTypes__
#   include "xr/BasicTypes.h"
#endif

#ifndef __Errno__
#   include "xr/Errno.h"
#endif

#define EBUG	4096	/* implementation detected bug */
#define EFMT	4097	/* format error in data */

/*
 * I/O procs (these belong in a different interface?)
 */

typedef int
(*XR_IOXferProc)(/*
    char *buf,
    int nBytes,
    XR_Pointer data
*/);
/*
    On success, behaves like Unix(tm) read or write,
        with file descriptor implicit in data.
    On failure, returns (-errno). 
*/

typedef int
(*XR_IOPositionProc)(/*
    int offset,
    int whence,
    XR_Pointer data
*/);
/*
    On success, behaves like Unix(tm) lseek,
        with file descriptor implicit in data.
    On failure, returns (-errno).
*/

/*
 * Generic Subsec callback proc
 */

typedef int
(*XR_ExtraSubsecCallbackProc)(/*
    char * subsecName,
    int subsecPos,
    int subsecBytes,
    XR_Pointer data
*/);
/*
    Returning negative value terminates caller.
*/


/*
 * Extra subsections are in groups separated by subsections of this name:
 */

extern char *
(XR_GetEndOfGroupSubsecName());


/*
 * Reading ...
 */

extern int
XR_EnumerateExtraSubsecs(/*
    XR_IOPositionProc lSeekProc,
    XR_IOXferProc readProc,
    XR_Pointer clientData,
    int subsecPos,
    XR_ExtraSubsecCallbackProc callbackProc,
    XR_Pointer callbackData
*/);
/*
    Enumerate extra subsections.
    Terminate enumeration if callbackProc returns non-zero.
    The value of subsecPos specifies where to start the enumeration:
        0 =>
            start at beginning of PCR subsecs
        (-1) =>
            start with first subsec of last PCR subsec group
        subsecPos value returned from previous call to FindExtraSubsec =>
            start with PCR subsec immediately following it
    Return 0 on success (even if callbackProc terminated enumeration
        by returning a positive value).
    Return (-errno) on failure (or if callbackProc terminated enumeration
        by returning (-errno) itself).
*/

extern int
XR_FindExtraSubsec(/*
    XR_IOPositionProc lSeekProc,
    XR_IOXferProc readProc,
    XR_Pointer clientData,
    char * subsecName,
    int * subsecPos,	// value-result
    int * subsecBytes	// result
*/);
/*
    Find specified extra subsection.
    Initial value of *subsecPos is treated as in XR_EnumerateExtraSubsecs.
    Return 0 on success,
        storing file position and length of extra subsection.
        (missing subsection is success with result pos = length = 0).
    Return (-errno) on failure.
*/


/*
 * Adding ...
 */

extern int
XR_AddSubsecGroup(/*
    XR_IOPositionProc lSeekProc,
    XR_IOXferProc readProc,
    XR_IOXferProc writeProc,
    XR_Pointer clientData
*/);
/*
    Add an empty subsec group at the end.
    Return pos of new end-of-group entry, or (-errno).
*/

extern int
XR_InsertExtraSubsec(/*
    XR_IOPositionProc lSeekProc,
    XR_IOXferProc readProc,
    XR_IOXferProc writeProc,
    XR_Pointer clientData,
    char * subsecName,
    int subsecBytes,
    int * subsecPos	// value-result
*/);
/*
    Insert new subsec of specified name and size immediately before
        existing subsec at specified position.
    If *subsecPos is initially (-1), new subsec is inserted at end of
        last subsec group.
    Set *subsecPos to position of of newly-created subsec (which is
        NOT guaranteed to be the same as the original value of *subsecPos).
    It is the client's responsibility to avoid duplicate subsec
      names in a subsec group if desired; see XR_DeleteExtraSubsec.
    Return 0 on success, storing in *subsecPos the offset
      where new subsec should be written.
    Return (-errno) on failure.
*/


extern int
XR_StartAddExtraSubsec(/*
    XR_IOPositionProc lSeekProc,
    XR_IOXferProc readProc,
    XR_IOXferProc writeProc,
    XR_Pointer clientData,
    char * subsecName,
    int * subsecPos	// result
*/);
/*
    Initialize file for adding subsection of given name to the
        last subsec group.
    It is the client's responsibility to avoid duplicate subsec
      names in a subsec group if desired; see XR_DeleteExtraSubsec.
    Return 0 on success, storing in *subsecPos the offset
      where new subsec should be written.
    Return (-errno) on failure.
*/

extern int
XR_FinishAddExtraSubsec(/*
    XR_IOPositionProc lSeekProc,
    XR_IOXferProc readProc,
    XR_IOXferProc writeProc,
    XR_Pointer clientData,
    int subsecBytes
*/);
/*
    Commit or abort (if subsecBytes < 0) adding of extra subsec.
    Return 0 on success, or (-errno) on failure.
*/


/*
 * Deleting ...
 */

extern int
XR_DeleteExtraSubsecs(/*
    XR_IOPositionProc lSeekProc,
    XR_IOXferProc readProc,
    XR_IOXferProc writeProc,
    XR_IOPositionProc fTruncateProc,
    XR_Pointer clientData,
    int subsecPos,
    XR_ExtraSubsecCallbackProc callbackProc,
    XR_Pointer callbackData
*/);
/*
    Delete subsections.
    Behavior is similar to Enumerate.
    The callbackProc should return >0 on subsecs that are to be
        deleted, 0 on subsecs that are not to be deleted, or (-errno).
    Return 0 on success, (-errno) on failure.
*/


extern int
XR_DeleteAllExtraSubsecs(/*
    XR_IOPositionProc lSeekProc,
    XR_IOXferProc readProc,
    XR_IOXferProc writeProc,
    XR_IOPositionProc fTruncateProc,
    XR_Pointer clientData,
*/);
/*
    Delete all subsections.
    Return 0 on success, (-errno) on failure.
*/


/*
 * Internals for wizards ...
 */

extern int
XR_GetADotOutExtraMagic(/*
*/);

extern int
XR_SetADotOutExtraMagic(/*
    int m;
*/);
/*
    Get/Set magic number for PCR extra section.
*/


#endif /* __PCRADotOutExtrasAccess__ */