← Back to branch summary

~ubuntu-branches/ubuntu/precise/kompozer/precise

« back to all changes in this revision

Viewing changes to mozilla/xpcom/io/nsIStreamBufferAccess.idl

  • Committer: Bazaar Package Importer
  • Author(s): Anthony Yarusso
  • Date: 2007-08-27 01:11:03 UTC
  • Revision ID: james.westby@ubuntu.com-20070827011103-2jgf4s6532gqu2ka
Tags: upstream-0.7.10
Import upstream version 0.7.10

Show diffs side-by-side

added added

removed removed

Lines of Context:
mozilla/xpcom/io/nsIStreamBufferAccess.idl
 
1
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
 
2
/* ***** BEGIN LICENSE BLOCK *****
 
3
 * Version: NPL 1.1/GPL 2.0/LGPL 2.1
 
4
 *
 
5
 * The contents of this file are subject to the Netscape Public License
 
6
 * Version 1.1 (the "License"); you may not use this file except in
 
7
 * compliance with the License. You may obtain a copy of the License at
 
8
 * http://www.mozilla.org/NPL/
 
9
 *
 
10
 * Software distributed under the License is distributed on an "AS IS" basis,
 
11
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 
12
 * for the specific language governing rights and limitations under the
 
13
 * License.
 
14
 *
 
15
 * The Original Code is Mozilla FastLoad code.
 
16
 *
 
17
 * The Initial Developer of the Original Code is 
 
18
 * Netscape Communications Corporation.
 
19
 * Portions created by the Initial Developer are Copyright (C) 2001
 
20
 * the Initial Developer. All Rights Reserved.
 
21
 *
 
22
 * Contributor(s):
 
23
 *   Brendan Eich <brendan@mozilla.org> (original author)
 
24
 *
 
25
 * Alternatively, the contents of this file may be used under the terms of
 
26
 * either the GNU General Public License Version 2 or later (the "GPL"), or 
 
27
 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 
28
 * in which case the provisions of the GPL or the LGPL are applicable instead
 
29
 * of those above. If you wish to allow use of your version of this file only
 
30
 * under the terms of either the GPL or the LGPL, and not to allow others to
 
31
 * use your version of this file under the terms of the NPL, indicate your
 
32
 * decision by deleting the provisions above and replace them with the notice
 
33
 * and other provisions required by the GPL or the LGPL. If you do not delete
 
34
 * the provisions above, a recipient may use your version of this file under
 
35
 * the terms of any one of the NPL, the GPL or the LGPL.
 
36
 *
 
37
 * ***** END LICENSE BLOCK ***** */
 
38
 
 
39
#include "nsISupports.idl"
 
40
#include "nsrootidl.idl"
 
41
 
 
42
/**
 
43
 * An interface for access to a buffering stream implementation's underlying
 
44
 * memory buffer.
 
45
 *
 
46
 * Stream implementations that QueryInterface to nsIStreamBufferAccess must
 
47
 * ensure that all buffers are aligned on the most restrictive type size for
 
48
 * the current architecture (e.g., sizeof(double) for RISCy CPUs).  malloc(3)
 
49
 * satisfies this requirement.
 
50
 */
 
51
[uuid(ac923b72-ac87-4892-ac7a-ca385d429435)]
 
52
interface nsIStreamBufferAccess : nsISupports
 
53
{
 
54
    /**
 
55
     * Get access to a contiguous, aligned run of bytes in the stream's buffer.
 
56
     * Exactly one successful getBuffer call must occur before a putBuffer call
 
57
     * taking the non-null pointer returned by the successful getBuffer.
 
58
     *
 
59
     * The run of bytes are the next bytes (modulo alignment padding) to read
 
60
     * for an input stream, and the next bytes (modulo alignment padding) to
 
61
     * store before (eventually) writing buffered data to an output stream.
 
62
     * There can be space beyond this run of bytes in the buffer for further
 
63
     * accesses before the fill or flush point is reached.
 
64
     *
 
65
     * @param aLength
 
66
     *    Count of contiguous bytes requested at the address A that satisfies
 
67
     *    (A & aAlignMask) == 0 in the buffer, starting from the current stream
 
68
     *    position, mapped to a buffer address B.  The stream implementation
 
69
     *    must pad from B to A by skipping bytes (if input stream) or storing
 
70
     *    zero bytes (if output stream).
 
71
     *
 
72
     * @param aAlignMask
 
73
     *    Bit-mask computed by subtracting 1 from the power-of-two alignment
 
74
     *    modulus (e.g., 3 or sizeof(PRUint32)-1 for PRUint32 alignment).
 
75
     *
 
76
     * @return
 
77
     *    The aligned pointer to aLength bytes in the buffer, or null if the
 
78
     *    buffer has no room for aLength bytes starting at the next address A
 
79
     *    after the current position that satisfies (A & aAlignMask) == 0.
 
80
     */
 
81
    [notxpcom] charPtr getBuffer(in PRUint32 aLength, in PRUint32 aAlignMask);
 
82
 
 
83
    /**
 
84
     * Relinquish access to the stream's buffer, filling if at end of an input
 
85
     * buffer, flushing if completing an output buffer.  After a getBuffer call
 
86
     * that returns non-null, putBuffer must be called.
 
87
     *
 
88
     * @param aBuffer
 
89
     *    A non-null pointer returned by getBuffer on the same stream buffer
 
90
     *    access object.
 
91
     *
 
92
     * @param aLength
 
93
     *    The same count of contiguous bytes passed to the getBuffer call that
 
94
     *    returned aBuffer.
 
95
     */
 
96
    [notxpcom] void putBuffer(in charPtr aBuffer, in PRUint32 aLength);
 
97
 
 
98
    /**
 
99
     * Disable and enable buffering on the stream implementing this interface.
 
100
     * DisableBuffering flushes an output stream's buffer, and invalidates an
 
101
     * input stream's buffer.
 
102
     */
 
103
    void disableBuffering();
 
104
    void enableBuffering();
 
105
 
 
106
    /**
 
107
     * The underlying, unbuffered input or output stream.
 
108
     */
 
109
    readonly attribute nsISupports unbufferedStream;
 
110
};
 
111
 
 
112
%{C++
 
113
 
 
114
// Swap macros, used to convert to/from canonical (big-endian) format
 
115
#if defined IS_LITTLE_ENDIAN
 
116
 
 
117
# define NS_SWAP16(x) ((((x) & 0xff) << 8) | (((x) >> 8) & 0xff))
 
118
# define NS_SWAP32(x) ((NS_SWAP16((x) & 0xffff) << 16) | (NS_SWAP16((x) >> 16)))
 
119
 
 
120
// We want to avoid casting to 32-bit types if possible, since that violates
 
121
// aliasing rules (a standard compiler may assume that pointers of two types
 
122
// do not address overlapping storage).
 
123
//
 
124
// XXX What if we have a compiler that follows aliasing rules strictly but
 
125
// doesn't have a 64-bit int type?
 
126
//
 
127
// XXXbe shouldn't NSPR's LL_INIT work for non-constant arguments in all cases?
 
128
 
 
129
# if defined HAVE_LONG_LONG
 
130
#  if PR_BYTES_PER_LONG == 8
 
131
#   define ULL_(x)     x ## UL
 
132
#  elif (defined WIN32 || defined WIN16) && !defined __GNUC__
 
133
#   define ULL_(x)     ((uint64) x ## i64)
 
134
#  else
 
135
#   define ULL_(x)     x ## ULL
 
136
#  endif
 
137
 
 
138
#  define NS_SWAP64(x) ((((x)    & ULL_(0xff00000000000000))    >> 56) |      \
 
139
                        (((x)    & ULL_(0x00ff000000000000))    >> 40) |      \
 
140
                        (((x)    & ULL_(0x0000ff0000000000))    >> 24) |      \
 
141
                        (((x)    & ULL_(0x000000ff00000000))    >> 8)  |      \
 
142
                        (((x)    & ULL_(0x00000000ff000000))    << 8)  |      \
 
143
                        (((x)    & ULL_(0x0000000000ff0000))    << 24) |      \
 
144
                        (((x)    & ULL_(0x000000000000ff00))    << 40) |      \
 
145
                        (((x) /* & ULL_(0x00000000000000ff) */) << 56))
 
146
# else
 
147
#  define NS_SWAP64(x) LL_INIT((((x).lo /* & 0xff000000ul */) >> 24) |        \
 
148
                               (((x).lo    & 0x00ff0000ul)    >> 8)  |        \
 
149
                               (((x).lo    & 0x0000ff00ul)    << 8)  |        \
 
150
                               (((x).lo /* & 0x000000fful */) << 24),         \
 
151
                               (((x).hi /* & 0xff000000ul */) >> 24) |        \
 
152
                               (((x).hi    & 0x00ff0000ul)    >> 8)  |        \
 
153
                               (((x).hi    & 0x0000ff00ul)    << 8)  |        \
 
154
                               (((x).hi /* & 0x000000fful */) << 24))
 
155
# endif
 
156
 
 
157
#elif defined IS_BIG_ENDIAN
 
158
 
 
159
# define NS_SWAP16(x) (x)
 
160
# define NS_SWAP32(x) (x)
 
161
# define NS_SWAP64(x) (x)
 
162
 
 
163
#else
 
164
 
 
165
# error "Unknown byte order"
 
166
 
 
167
#endif
 
168
 
 
169
/**
 
170
 * These macros get and put a buffer given either an sba parameter that may
 
171
 * point to an object implementing nsIStreamBufferAccess, nsIObjectInputStream,
 
172
 * or nsIObjectOutputStream.
 
173
 */
 
174
#define NS_GET_BUFFER(sba,n,a)  ((sba)->GetBuffer(n, a))
 
175
#define NS_PUT_BUFFER(sba,p,n)  ((sba)->PutBuffer(p, n))
 
176
 
 
177
#define NS_GET8(p)              (*(PRUint8*)(p))
 
178
#define NS_GET16(p)             NS_SWAP16(*(PRUint16*)(p))
 
179
#define NS_GET32(p)             NS_SWAP32(*(PRUint32*)(p))
 
180
#define NS_GET64(p)             NS_SWAP64(*(PRUint64*)(p))
 
181
#define NS_GET_FLOAT(p)         ((float)NS_SWAP32(*(PRUint32*)(p)))
 
182
#define NS_GET_DOUBLE(p)        ((double)NS_SWAP64(*(PRUint64*)(p)))
 
183
 
 
184
#define NS_PUT8(p,x)            (*(PRUint8*)(p) = (x))
 
185
#define NS_PUT16(p,x)           (*(PRUint16*)(p) = NS_SWAP16(x))
 
186
#define NS_PUT32(p,x)           (*(PRUint32*)(p) = NS_SWAP32(x))
 
187
#define NS_PUT64(p,x)           (*(PRUint64*)(p) = NS_SWAP64(x))
 
188
#define NS_PUT_FLOAT(p,x)       (*(PRUint32*)(p) = NS_SWAP32(*(PRUint32*)&(x)))
 
189
#define NS_PUT_DOUBLE(p,x)      (*(PRUint64*)(p) = NS_SWAP64(*(PRUint64*)&(x)))
 
190
 
 
191
%}