/* 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←← */