prj/tech/libsrc/compapis/arqapi.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // $Source: x:/prj/tech/libsrc/compapis/RCS/arqapi.h $
   3 // $Author: TOML $
   4 // $Date: 1997/09/18 13:04:50 $
   5 // $Revision: 1.12 $
   6 //
   7
   8 #ifndef __ARQAPI_H
   9 #define __ARQAPI_H
  10
  11 #include <comtools.h>
  12 #include <prikind.h>
  13 #include <arqguid.h>
  14
  15 #include <pshpack4.h>
  16
  17 ///////////////////////////////////////////////////////////////////////////////
  18
  19 struct IStream; typedef struct IStream IStream;
  20
  21 F_DECLARE_INTERFACE(IAsyncReadQueue);
  22 F_DECLARE_INTERFACE(IAsyncReadControl);
  23 F_DECLARE_INTERFACE(IAsyncReadFulfiller);
  24 F_DECLARE_INTERFACE(IAsyncStreamer);
  25
  26 typedef struct sARQResult         sARQResult;
  27 typedef struct sARQRequest        sARQRequest;
  28 typedef struct sARQStreamerDesc   sARQStreamerDesc;
  29 typedef struct sARQStreamRequest  sARQStreamRequest;
  30
  31 ///////////////////////////////////////////////////////////////////////////////
  32 //
  33 // Asynchronous Read Queue API
  34 //
  35
  36 //
  37 // Create an asynchronous read queue and add it to the global app-object
  38 //
  39 #define AsyncReadQueueCreate() \
  40 { \
  41     IUnknown * pAppUnknown = AppGetObj(IUnknown); \
  42     _AsyncReadQueueCreate(IID_TO_REFIID(IID_IAsyncReadQueue), NULL, pAppUnknown); \
  43     COMRelease(pAppUnknown); \
  44 }
  45
  46
  47 //
  48 // Creates an asynchronous read queue, aggregating it with specfied pOuter,
  49 // use IAggregate protocol if ppAsyncReadQueue is NULL, else self-init
  50 //
  51 EXTERN tResult LGAPI _AsyncReadQueueCreate(REFIID, IAsyncReadQueue ** ppAsyncReadQueue, IUnknown * pOuter);
  52
  53
  54 ///////////////////////////////////////////////////////////////////////////////
  55 //
  56 // Read request structures
  57 //
  58
  59 ///////////////////////////////////////
  60 //
  61 // STRUCT: sARQRequest
  62 //
  63
  64 struct sARQRequest
  65 {
  66     // Pointer to object used to execute read
  67     IAsyncReadFulfiller *   pFulfiller;
  68
  69     // Queue to use, zero-based
  70     unsigned                queue;
  71
  72     // Priority of read
  73     int                     priority;
  74
  75     // Optional, client defined data values
  76     DWORD                   dwData[6];
  77
  78     // Optional tracing name for debug routines
  79     const char *            pszTrace;
  80
  81 };
  82
  83
  84 ///////////////////////////////////////
  85 //
  86 // STRUCT: sARQStreamRequest
  87 //
  88
  89 struct sARQStreamRequest
  90 {
  91     // Source of read
  92     IStream *       pSource;
  93
  94     // Starting offset, may be kARQCurPos
  95     long            offset;
  96
  97     // Length of read, may be kARQToEOF
  98     long            length;
  99
 100     // Queue to use, zero-based
 101     unsigned        queue;
 102
 103     // Priority of read
 104     int             priority;
 105
 106     // Flags composed of bits from eARQStreamRequestFlags
 107     int             flags;
 108
 109     // Destination, may be NULL if dynamic allocation is desired
 110     void *          pBufOut;
 111
 112     // Destination size
 113     long            bufSize;
 114
 115     // Optional tracing name for debug routines
 116     const char *    pszTrace;
 117
 118 };
 119
 120 // Helper macro
 121 #define ARQInitStreamReq(arqreq, src, off, len, que, pri, f, p, sz, nm); \
 122 { \
 123     arqreq.pSource = src; \
 124     arqreq.offset = off; \
 125     arqreq.length = len; \
 126     arqreq.queue = que; \
 127     arqreq.priority = pri; \
 128     arqreq.flags = f; \
 129     arqreq.pBufOut = p; \
 130     arqreq.bufSize = sz; \
 131     arqreq.pszTrace = nm; \
 132 }
 133
 134
 135 ///////////////////////////////////////
 136
 137 #define kARQCurPos   (-1L)
 138 #define kARQToEOF    (-1L)
 139
 140
 141 ///////////////////////////////////////
 142
 143 enum eARQStreamRequestFlags
 144 {
 145     // Specified buffer may safely be realloced
 146     kARQDynamicBuf = 0x01
 147 };
 148
 149
 150 ///////////////////////////////////////////////////////////////////////////////
 151 //
 152 // STRUCT: sARQResult
 153 //
 154
 155 struct sARQResult
 156 {
 157     // Status of the result
 158     HRESULT     result;
 159
 160     // Result, whether dynamically allocated or buffer supplied
 161     void *      buffer;
 162
 163     // Size of the result
 164     long        length;
 165
 166     // Flags, composed of bits from eARQResultFlags
 167     unsigned    flags;
 168
 169     // Number of read, if streaming 0 if starting, 'frame number' on
 170     // subsequent reads
 171     int         streamIndex;
 172
 173 };
 174
 175
 176 ///////////////////////////////////////
 177
 178 enum eARQResultFlags
 179 {
 180     // The buffer was malloc’ed by read queue system
 181     kARQMalloc    = 0x01,
 182
 183     // The request is associated with streaming data
 184     kARQStreamed  = 0x02,
 185
 186     // The request was killed
 187     kARQKilled    = 0x04
 188
 189 };
 190
 191
 192 ///////////////////////////////////////////////////////////////////////////////
 193 //
 194 // STRUCT: sARQStreamerDesc
 195 //
 196
 197 struct sARQStreamerDesc
 198 {
 199     // Source of read
 200     IStream *       pSource;
 201
 202     // Starting offset, may be kARQCurPos
 203     long            offsetStart;
 204
 205     // Length of header
 206     long            lenHeader;
 207
 208     // Queue to use, zero-based
 209     unsigned        queue;
 210
 211     // Priority of read
 212     int             priority;
 213
 214     // Flags composed of bits from eAsyncStreamerFlags
 215     int             flags;
 216
 217     // Destination of header read, if lenHeader specified.
 218     // May be NULL if dynamic allocation is desired
 219     void *          pBufOut;
 220
 221     // Destination size
 222     long            bufSize;
 223
 224     // Optional tracing name for debug routines
 225     const char *    pszTrace;
 226
 227 };
 228
 229
 230 // Helper macro
 231 #define ARQInitStrDesc(strdsc, src, off, len, que, pri, f, p, sz, nm); \
 232 { \
 233     strdsc.pSource = src; \
 234     strdsc.offsetStart = off; \
 235     strdsc.lenHeader = len; \
 236     strdsc.queue = que; \
 237     strdsc.priority = pri; \
 238     strdsc.flags = f; \
 239     strdsc.pBufOut = p; \
 240     strdsc.bufSize = sz; \
 241     strdsc.pszTrace = nm; \
 242 }
 243
 244
 245 ///////////////////////////////////////
 246
 247 enum eAsyncStreamerFlags
 248 {
 249     // The stream should preempt all others in the same queue, for its lifetime
 250     kAsStrExclusive     = 0x01
 251
 252 };
 253
 254
 255 ///////////////////////////////////////////////////////////////////////////////
 256 //
 257 // INTERFACE: IAsyncReadQueue
 258 //
 259
 260 #undef INTERFACE
 261 #define INTERFACE IAsyncReadQueue
 262
 263 DECLARE_INTERFACE_(IAsyncReadQueue, IUnknown)
 264 {
 265     //
 266     // IUnknown Methods
 267     //
 268     DECLARE_UNKNOWN_PURE();
 269
 270     //
 271     // Add a simple request to queue
 272     //
 273     STDMETHOD (QueueRequest)(THIS_ const sARQRequest * pRequest,
 274                                    IAsyncReadControl ** ppControl) PURE;
 275
 276     //
 277     // Add a simple stream-oriented request to queue
 278     //
 279     STDMETHOD (QueueStreamRequest)(THIS_ const sARQStreamRequest * pRequest,
 280                                          IAsyncReadControl ** ppControl) PURE;
 281
 282     //
 283     // Get a reader for streaming
 284     //
 285     STDMETHOD (GetAsyncStreamer)(THIS_ const sARQStreamerDesc * pDesc,
 286                                        IAsyncStreamer ** ppAsyncStreamer) PURE;
 287
 288     //
 289     // Suspend all reads
 290     //
 291     STDMETHOD (Suspend)(THIS) PURE;
 292
 293     //
 294     // Resume reading
 295     //
 296     STDMETHOD (Resume)(THIS) PURE;
 297
 298     //
 299     // Query if a streamer is blocking
 300     //
 301     STDMETHOD_(BOOL, IsStreamerBlocking)(THIS) PURE;
 302
 303     //
 304     // Synchronously satisfy all pending requests -- analogous to flush
 305     //
 306     STDMETHOD (FulfillAll)(THIS) PURE;
 307
 308     //
 309     // Synchronously satisfy all pending requests with priority equal to or
 310     // higher than the specified priority
 311     //
 312     STDMETHOD (FulfillToPriority)(THIS_ int priority) PURE;
 313
 314     //
 315     // Kill all pending requests
 316     //
 317     STDMETHOD (KillAll)(THIS) PURE;
 318
 319 };
 320
 321
 322 // @TBD (toml 11-12-96): need to finish coding up all these C access macros!
 323 #define IAsyncReadQueue_QueryInterface(p, a, b)  COMQueryInterface(p, a, b)
 324 #define IAsyncReadQueue_AddRef(p)                COMAddRef(p)
 325 #define IAsyncReadQueue_Release(p)               COMRelease(p)
 326 #define IAsyncReadQueue_QueueRequest(p, a, b)    COMCall2(p, QueueRequest, a, b)
 327 #define IAsyncReadQueue_FulfillAll(p)            COMCall0(p, FulfillAll)
 328
 329 ///////////////////////////////////////////////////////////////////////////////
 330 //
 331 // INTERFACE: IAsyncReadFulfiller
 332 //
 333
 334 #undef INTERFACE
 335 #define INTERFACE IAsyncReadFulfiller
 336
 337 DECLARE_INTERFACE_(IAsyncReadFulfiller, IUnknown)
 338 {
 339     //
 340     // IUnknown Methods
 341     //
 342     DECLARE_UNKNOWN_PURE();
 343
 344     //
 345     // Satisfy the request
 346     //
 347     STDMETHOD (DoFulfill)(THIS_ const sARQRequest *, sARQResult *) PURE;
 348
 349     //
 350     // Kill the request, discard if paritally or wholly fulfilled
 351     //
 352     STDMETHOD (DoKill)(THIS_ const sARQRequest *, BOOL fDiscard) PURE;
 353
 354 };
 355
 356
 357 ///////////////////////////////////////////////////////////////////////////////
 358 //
 359 // INTERFACE: IAsyncReadControl
 360 //
 361
 362 #undef INTERFACE
 363 #define INTERFACE IAsyncReadControl
 364
 365 DECLARE_INTERFACE_(IAsyncReadControl, IUnknown)
 366 {
 367     //
 368     // IUnknown Methods
 369     //
 370     DECLARE_UNKNOWN_PURE();
 371
 372     //
 373     // Query if request has been fulfilled
 374     //
 375     STDMETHOD_(BOOL, IsFulfilled)(THIS) PURE;
 376
 377     //
 378     // Synchronously satisfy the request
 379     //
 380     STDMETHOD (Fulfill)(THIS) PURE;
 381
 382     //
 383     // Kill the request, discard if paritally or wholly fulfilled
 384     //
 385     STDMETHOD (Kill)(THIS_ BOOL fDiscard) PURE;
 386
 387     //
 388     // Get the result
 389     //
 390     STDMETHOD (GetResult)(THIS_ sARQResult *) PURE;
 391
 392 };
 393
 394
 395 ///////////////////////////////////////////////////////////////////////////////
 396 //
 397 // INTERFACE: IAsyncStreamer
 398 //
 399
 400 #undef INTERFACE
 401 #define INTERFACE IAsyncStreamer
 402
 403 DECLARE_INTERFACE_(IAsyncStreamer, IUnknown)
 404 {
 405     //
 406     // IUnknown Methods
 407     //
 408     DECLARE_UNKNOWN_PURE();
 409
 410     //
 411     //
 412     //
 413     STDMETHOD (Read)(THIS_ void * pBufOut, long length) PURE;
 414
 415     //
 416     //
 417     //
 418     STDMETHOD (GetNextResult)(THIS_ sARQResult *) PURE;
 419
 420     //
 421     // Synchronously satisfy all pending requests from this stream -- analogous
 422     // to flush
 423     //
 424     STDMETHOD (FulfillAll)(THIS) PURE;
 425
 426     //
 427     // Kill all pending requests from this stream
 428     //
 429     STDMETHOD (KillAll)(THIS_ BOOL fDiscard) PURE;
 430
 431 };
 432
 433
 434 ///////////////////////////////////////////////////////////////////////////////
 435
 436 #include <poppack.h>
 437
 438 #endif /* !__ARQAPI_H */