Estructura SDL_RWops

Una estructura que proporciona una interfaz abstracta para el flujo de E/S. Por lo general, las aplicaciones pueden ignorar los detalles internos de esta estructura y tratarlos como punteros opacos. Sin embargo, los detalles son importantes para el código de bajo nivel que pueda necesitar implementar alguna de ellas.

typedef struct SDL_RWops
{
    Sint64 (SDLCALL * size) (struct SDL_RWops * context);
    Sint64 (SDLCALL * seek) (struct SDL_RWops * context, Sint64 offset,
                             int whence);
    size_t (SDLCALL * read) (struct SDL_RWops * context, void *ptr,
                             size_t size, size_t maxnum);
    size_t (SDLCALL * write) (struct SDL_RWops * context, const void *ptr,
                              size_t size, size_t num);
    int (SDLCALL * close) (struct SDL_RWops * context);
    Uint32 type;
    union
    {
#if defined(__ANDROID__)
        struct
        {
            void *asset;
        } androidio;
#elif defined(__WIN32__) || defined(__GDK__)
        struct
        {
            SDL_bool append;
            void *h;
            struct
            {
                void *data;
                size_t size;
                size_t left;
            } buffer;
        } windowsio;
#endif

#ifdef HAVE_STDIO_H
        struct
        {
            SDL_bool autoclose;
            FILE *fp;
        } stdio;
#endif
        struct
        {
            Uint8 *base;
            Uint8 *here;
            Uint8 *stop;
        } mem;
        struct
        {
            void *data1;
            void *data2;
        } unknown;
    } hidden;

} SDL_RWops;

Miembros

size

Retrollamada que devuelve el tamaño del stream.

seek

Retrollamada que busca en el stream.

read

Retrollamada que lee desde el stream.

write

Retrollamada que escribe en el stream.

close

Retrollamada que cierra el stream.

type

Tipo de stream.

hidden

Datos específicos del tipo.

Ejemplos

SDL_RWops *io = SDL_RWFromFile("username.txt", "rb");
if (io != NULL) {
    char name[256];
    if (io->read(io, name, sizeof (name), 1) > 0) {
        printf("Hello, %s!\n", name);
    }
    io->close(io);
}

El siguiente ejemplo tiene un funcionalmente idéntico al anterior, pero utiliza la interfaz de macros recomendada.

SDL_RWops *io = SDL_RWFromFile("username.txt", "rb");
if (io != NULL) {
    char name[256];
    if (SDL_RWread(io, name, sizeof (name), 1) > 0) {
        printf("Hello, %s!\n", name);
    }
    SDL_RWclose(io);
}

Observaciones

SDL_RWops es una abstracción sobre E/S. Proporciona interfaces para leer, escribir y buscar datos en un stream, sin que el proceso que llama necesite saber de dónde vienen los datos.

Por ejemplo, un RWops puede ser alimentado por un buffer de memoria, o un archivo en disco, o una conexión a un servidor web, sin ningún cambio en cómo el llamador consume los datos.

SDL proporciona algunos métodos internos para leer desde tipos de streams comunes, como archivos y buffers de memoria, pero esta estructura puede ser utilizada por la aplicación o por librerías de terceros para implementar cualquier tipo de flujo que le plazca.

La mayoría de los campos de esta estructura son punteros a funciones que se utilizan como retrollamadas para implementar la interfaz de stream. Todos ellos utilizan la convención de llamada SDLCALL.

Ha y que tener en cuenta que muchos de estos punteros de función utilizaban ints en SDL 1.2; para darles un mejor rango, se han convertido en Sint64 en SDL 2.0.

Las aplicaciones no deberían tener que preocuparse por los aspectos internos de esta estructura. Pueden tratarla como un puntero de datos opaco y usar las funciones SDL_RWread(), SDL_RWwrite(), SDL_RWseek(), SDL_RWtell() y SDL_RWclose() sobre ellas. Las aplicaciones casi nunca crean o modifican estas estructuras, sino que prefieren funciones de creación como SDL_RWFromFile(), SDL_RWFromMem(), etc.

Sin embargo, las bibliotecas de terceros y el código especial de bajo nivel pueden necesitar saber cómo implementar correctamente esta estructura.

Función size

size es un puntero de función que informa del tamaño total del stream en bytes. Si no se puede determinar el tamaño del stream (ya sea porque no tiene sentido para ese tipo de stream o porque se ha producido un error), esta función devuelve -1.

Función seek

seek es un puntero de función que posiciona la siguiente operación de lectura/escritura en el stream. Se busca en desplazamientos de bytes. Si el stream no puede buscar (ya sea porque no tiene sentido para el tipo de stream, o hubo un error), esta función devuelve -1, de lo contrario devuelve la nueva posición. Buscar cero bytes desde RW_SEEK_CUR es una forma común de determinar la posición actual del stream.

El argumento final funciona como el "whence" estándar de fseek():

Identificador	Valor	Explicación
RW_SEEK_SET	0	Busca desde el principio de los datos.
RW_SEEK_CUR	1	Busca en relación a la posición de lectura actual.
RW_SEEK_END	2	Busca en relación a la posición final de los datos.

Función read

read es un puntero de función que lee del stream. Lee hasta num objetos cada uno de tamaño bytes en el puntero del buffer apuntado por ptr. Devuelve el número de objetos leídos, que puede ser inferior al solicitado. Devuelve 0 en caso de error o EOF.

Función write

write es un puntero de función que escribe en el stream. Escribe exactamente num objetos cada uno de tamaño bytes desde el puntero al buffer apuntado por ptr. Devuelve el número de objetos escritos, que será menor que el solicitado si se produce un error.

Función close

close es un puntero de función que cierra el stream. Debería liberar cualquier recurso usado por el stream y liberar el propio SDL_RWops con SDL_FreeRW(). Devuelve 0 en caso de éxito, o -1 si el stream falló al vaciarse en disco (o donde sea). El SDL_RWops ya no será válido después de esta llamada, incluso si el stream falló.

Tipo de stream

El campo de tipo es uno de estos valores. Por lo general, una aplicación puede ignorar esta información.

Identificador	Valor	Descrición
SDL_RWOPS_UNKNOWN	0	Tipo de stream desconocido o definido por la aplicación.
SDL_RWOPS_WINFILE	1	Manipulador de fichero Win32.
SDL_RWOPS_STDFILE	2	FILE* de stdio.
SDL_RWOPS_JNIFILE	3	assert Android.
SDL_RWOPS_MEMORY	4	Stream de memoria (lectura/escritura).
SDL_RWOPS_MEMORY_RO	5	Stream de memoria (solo lectura)

Las aplicaciones y bibliotecas que desarrollen sus propias implementaciones de RWops deberían utilizar SDL_RWOPS_UNKNOWN. Todos los demás valores están actualmente reservados para uso interno de SDL.

Unión oculta

Las aplicaciones pueden ignorar completamente esta unión. Todos sus campos son específicos de la plataforma y están fuera de los límites, son usados internamente por SDL, con una excepción. Se puede utilizar el struct desconocido para almacenar los datos de una implementación propia de RWops, posiblemente limpiándolos durante el método close. Si los datos no caben en dos punteros, se utilizan estos punteros para mantener una estructura asignada que contenga los datos reales.