document IAGSStream in the Engine Runtime Plugin API

[ericoporto]

Document IAGSStream here https://github.com/adventuregamestudio/ags-manual/wiki/EnginePluginRun-timeAPI

link to it

class IAGSStream {
public:
  // Tells which mode the stream is working in, which defines
  // supported io operations, such as reading, writing, seeking, etc.
  // Returns combination of AGSSTREAM_MODE_* flags.
  // Invalid or non-functional streams return 0.
  virtual int    GetMode() const = 0;
  // Returns an optional stream's source description.
  // This may be a file path, or a resource name, or anything of that kind,
  // and is purely for diagnostic purposes.
  virtual const char *GetPath() const = 0;
  // Tells whether this stream's position is at its end;
  // note that unlike standard C feof this does not wait for a read attempt
  // past the stream end, and reports positive when position = length.
  virtual bool   EOS() const = 0;
  // Tells if there were errors during previous io operation(s);
  // the call to GetError() *resets* the error record.
  virtual bool   GetError() const = 0;
  // Returns the total stream's length in bytes
  virtual int64_t GetLength() const = 0;
  // Returns stream's position
  virtual int64_t GetPosition() const = 0;

  // Reads number of bytes into the provided buffer
  virtual size_t Read(void *buffer, size_t len) = 0;
  // ReadByte conforms to standard C fgetc behavior:
  // - on success returns an *unsigned char* packed in the int32
  // - on failure (EOS or other error), returns -1
  virtual int32_t ReadByte() = 0;
  // Writes number of bytes from the provided buffer
  virtual size_t Write(const void *buffer, size_t len) = 0;
  // WriteByte conforms to standard C fputc behavior:
  // - on success, returns the written unsigned char packed in the int32
  // - on failure, returns -1
  virtual int32_t WriteByte(uint8_t b) = 0;
  // Seeks to offset from the origin defined by AGSSTREAM_SEEK_* constants:
  //  * AGSSTREAM_SEEK_SET - seek from the beginning;
  //  * AGSSTREAM_SEEK_CUR - seek from the current position;
  //  * AGSSTREAM_SEEK_END - seek from the end (pass negative offset)
  // Returns new position in stream, or -1 on error.
  virtual int64_t Seek(int64_t offset, int origin) = 0;
  // Flushes stream, forcing it to write any buffered data to the
  // underlying device. Note that the effect may depend on implementation.
  virtual bool   Flush() = 0;
  // Flushes and closes the stream.
  // Usually you do not have to call this, use Dispose() to close
  // and delete stream object instead.
  virtual void   Close() = 0;

  // Closes the stream and deallocates the stream object.
  // After calling this the IAGSStream pointer becomes INVALID.
  virtual void   Dispose() = 0;

protected:
  IAGSStream() = default;
  ~IAGSStream() = default;
};

Creating it here

  // *** BELOW ARE INTERFACE VERSION 28 AND ABOVE ONLY
  // Opens a data stream, resolving a script path.
  // File mode should contain one of the AGSSTREAM_FILE_* values,
  // work mode should contain flag set of the AGSSTREAM_MODE_* values.
  // Returns IAGSStream object, or null on failure. The returned stream object
  // is owned by the caller, and must be deleted by calling its Dispose() method.
  AGSIFUNC(IAGSStream*) OpenFileStream(const char *script_path, int file_mode, int work_mode);
  // Returns IAGSStream object identified by the given stream handle.
  // This lets to retrieve IAGSStream object from a handle received in a event callback.
  // *IMPORTANT*: The returned stream's ownership is NOT passed to the caller;
  // this stream should not be closed or disposed, doing so will lead to errors in the engine.
  // Returns null if handle is invalid.
  AGSIFUNC(IAGSStream*) GetFileStreamByHandle(int32 fhandle);

[ivan-mogilko]

Added: https://github.com/adventuregamestudio/ags-manual/wiki/EnginePluginRun-timeAPI/_compare/0b710569b44928f7725d4b7b41d2a1c8f7e8ae34...840e626029fd827a44643acb45d1e759aa0442e5

[ericoporto]

Thanks!