guacamole-spice-protocol/src/guacenc/image-stream.h
2016-03-28 20:39:19 -07:00

233 lines
7.0 KiB
C

/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
#ifndef GUACENC_IMAGE_STREAM_H
#define GUACENC_IMAGE_STREAM_H
#include "config.h"
#include "buffer.h"
#include <cairo/cairo.h>
/**
* The initial number of bytes to allocate for the image data buffer. If this
* buffer is not sufficiently large, it will be dynamically reallocated as it
* grows.
*/
#define GUACENC_IMAGE_STREAM_INITIAL_LENGTH 4096
/**
* Callback function which is provided raw, encoded image data of the given
* length. The function is expected to return a new Cairo surface which will
* later (by guacenc) be freed via cairo_surface_destroy().
*
* @param data
* The raw encoded image data that this function must decode.
*
* @param length
* The length of the image data, in bytes.
*
* @return
* A newly-allocated Cairo surface containing the decoded image, or NULL
* or decoding fails.
*/
typedef cairo_surface_t* guacenc_decoder(unsigned char* data, int length);
/**
* The current state of an allocated Guacamole image stream.
*/
typedef struct guacenc_image_stream {
/**
* The index of the destination layer or buffer.
*/
int index;
/**
* The Guacamole protocol compositing operation (channel mask) to apply
* when drawing the image.
*/
int mask;
/**
* The X coordinate of the upper-left corner of the rectangle within the
* destination layer or buffer that the decoded image should be drawn to.
*/
int x;
/**
* The Y coordinate of the upper-left corner of the rectangle within the
* destination layer or buffer that the decoded image should be drawn to.
*/
int y;
/**
* Buffer of image data which will be built up over time as chunks are
* received via "blob" instructions. This will ultimately be passed in its
* entirety to the decoder function.
*/
unsigned char* buffer;
/**
* The number of bytes currently stored in the buffer.
*/
int length;
/**
* The maximum number of bytes that can be stored in the current buffer
* before it must be reallocated.
*/
int max_length;
/**
* The decoder to use when decoding the raw data received along this
* stream, or NULL if no such decoder exists.
*/
guacenc_decoder* decoder;
} guacenc_image_stream;
/**
* Mapping of image mimetype to corresponding decoder function.
*/
typedef struct guacenc_decoder_mapping {
/**
* The mimetype of the image that the associated decoder can read.
*/
const char* mimetype;
/**
* The decoder function to use when an image stream of the associated
* mimetype is received.
*/
guacenc_decoder* decoder;
} guacenc_decoder_mapping;
/**
* Array of all mimetype/decoder mappings for all supported image types,
* terminated by an entry with a NULL mimetype.
*/
extern guacenc_decoder_mapping guacenc_decoder_map[];
/**
* Returns the decoder associated with the given mimetype. If no such decoder
* exists, NULL is returned.
*
* @param mimetype
* The image mimetype to return the associated decoder of.
*
* @return
* The decoder associated with the given mimetype, or NULL if no such
* decoder exists.
*/
guacenc_decoder* guacenc_get_decoder(const char* mimetype);
/**
* Allocates and initializes a new image stream. This allocation is independent
* of the Guacamole video encoder display; the allocated guacenc_image_stream
* will not automatically be associated with the active display, nor will the
* provided layer/buffer index be validated.
*
* @param mask
* The Guacamole protocol compositing operation (channel mask) to apply
* when drawing the image.
*
* @param index
* The index of the layer or buffer that the image should be drawn to.
*
* @param mimetype
* The mimetype of the image data that will be received along this stream.
*
* @param x
* The X coordinate of the upper-left corner of the rectangle within the
* destination layer or buffer that the image should be drawn to.
*
* @param y
* The Y coordinate of the upper-left corner of the rectangle within the
* destination layer or buffer that the image should be drawn to.
*
* @return
* A newly-allocated and initialized guacenc_image_stream, or NULL if
* allocation fails.
*/
guacenc_image_stream* guacenc_image_stream_alloc(int mask, int index,
const char* mimetype, int x, int y);
/**
* Appends newly-received data to the internal buffer of the given image
* stream, such that the entire received image can be fed to the decoder as one
* buffer once the stream ends.
*
* @param stream
* The image stream that received the data.
*
* @param data
* The chunk of data received along the image stream.
*
* @param length
* The length of the chunk of data received, in bytes.
*
* @return
* Zero if the given data was successfully appended to the in-progress
* image, non-zero if an error occurs.
*/
int guacenc_image_stream_receive(guacenc_image_stream* stream,
unsigned char* data, int length);
/**
* Marks the end of the given image stream (no more data will be received) and
* invokes the associated decoder. The decoded image will be written to the
* given buffer as-is. If no decoder is associated with the given image stream,
* this function has no effect. Meta-information describing the image draw
* operation itself is pulled from the guacenc_image_stream, having been stored
* there when the image stream was created.
*
* @param stream
* The image stream that has ended.
*
* @param buffer
* The buffer that the decoded image should be written to.
*
* @return
* Zero if the image is written successfully, or non-zero if an error
* occurs.
*/
int guacenc_image_stream_end(guacenc_image_stream* stream,
guacenc_buffer* buffer);
/**
* Frees the given image stream and all associated data. If the image stream
* has not yet ended (reached end-of-stream), no image will be drawn to the
* associated buffer or layer.
*
* @param stream
* The stream to free.
*
* @return
* Zero if freeing the stream succeeded, or non-zero if freeing the stream
* failed (for example, due to an error in the free handler of the
* decoder).
*/
int guacenc_image_stream_free(guacenc_image_stream* stream);
#endif