Initial revision

[ssr] / StraySrc / Libraries / Steel / h / xferrecv

/****************************************************************************
 * This source file was written by Acorn Computers Limited. It is part of   *
 * the RISCOS library for writing applications in C for RISC OS. It may be  *
 * used freely in the creation of programs for Archimedes. It should be     *
 * used with Acorn's C Compiler Release 3 or later.                         *
 *                                                                          *
 ***************************************************************************/

/*----- Licensing note ----------------------------------------------------*
 *
 * This file is part of Straylight's Steel library.
 *
 * Steel is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2, or (at your option)
 * any later version.
 *
 * Steel is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with Steel.  If not, write to the Free Software Foundation,
 * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 */

/* Title:   xferrecv.h
 * Purpose: general purpose import of data by dragging icon
 *
 */

#ifndef __xferrecv_h
#define __xferrecv_h

#ifndef __flex_h
  #include "flex.h"
#endif

#ifndef BOOL
#define BOOL int
#define TRUE 1
#define FALSE 0
#endif


/* -------------------------- xferrecv_checkinsert -------------------------
 * Description:   Set up the acknowledge message for a MDATAOPEN or MDATALOAD
 *                and get filename to load from.
 *
 * Parameters:    char **filename -- returned pointer to filename
 * Returns:       the file's type (eg. 0x0fff for !Edit)
 * Other Info:    This function checks to see if the last wimp event was a 
 *                request to import a file. If so it returns file type and
 *                a pointer to file's name is put into *filename. If not
 *                it returns -1.   
 *
 */

int xferrecv_checkinsert(char **filename);


/* --------------------------- xferrecv_insertfileok -----------------------
 * Description:   Deletes scrap file (if used for transfer), and sends
 *                acknowledgement of MDATALOAD message.
 *
 * Parameters:    void
 * Returns:       void.
 * Other Info:    none.
 *
 */

void xferrecv_insertfileok(void);


/* --------------------------- xferrecv_checkprint -------------------------
 * Description:   Set up acknowledge message to a MPrintTypeOdd message
 *                and get file name to print.
 *
 * Parameters:    char **filename -- returned pointer to filename
 * Returns:       The file's type (eg. 0x0fff for !Edit).
 * Other Info:    Application can either print file directly or convert it to
 *                <Printer$Temp> for printing by the printer application.
 *
 */

int xferrecv_checkprint(char **filename);


/* --------------------------- xferrecv_printfileok ------------------------
 * Description:   Send an acknowledgement back to printer application. If
 *                file sent to <Printer$Temp> then this also fills in file
 *                type in message.
 *
 * Parameters:    int type -- type of file sent to <Printer$Temp> 
 *                            (eg. 0x0fff for !edit)
 * Returns:       void.
 * Other Info:    none.
 *
 */

void xferrecv_printfileok(int type);


/* ---------------------------- xferrecv_checkimport -----------------------
 * Description:   Set up acknowledgement message to a MDATASAVE message.
 *
 * Parameters:    int *estsize -- sender's estimate of file size
 * Returns:       File type.
 * Other Info:    none.
 *
 */

int xferrecv_checkimport(int *estsize);

/*
 * char *xferrecv_nameToImport(void)
 *
 * Use
 *  Returns the name of the file to import (full pathname if available).
 *
 * Returns
 *  A pointer to a read-only string.
 */

char *xferrecv_nameToImport(void);

/*
 * void xferrecv_importByScrap(void)
 *
 * Use
 *  Tells xferrecv not to bother with RAM transfer, but to use the
 *  <Wimp$Scrap> file instead.  It checks that the system variables and
 *  everything are set up right beforehand.
 */

void xferrecv_importByScrap(void);

/* ------------------------- xferrecv_buffer_processor ---------------------
 * Description:   This is a typedef for the caller-supplied function
 *                to empty a full buffer during data transfer.
 *
 * Parameters:    char **buffer -- new buffer to be used
 *                int *size -- updated size
 * Returns:       return FALSE if unable to empty buffer or create new one.
 * Other Info:    This is the function (supplied by application,) which will
 *                be called when buffer is full. It should empty the current
 *                buffer, or create more space and modify size accordingly
 *                or return FALSE. *buffer and *size are the current buffer
 *                and its size on function entry.
 *
 */
 
typedef BOOL (*xferrecv_buffer_processor)(char **buffer, int *size);



/* ---------------------------- xferrecv_doimport --------------------------
 * Description:   Loads data into a buffer, and calls the caller-supplied
 *                function to empty the buffer when full.
 *
 * Parameters:    char *buf -- the buffer
 *                int size -- buffer's size
 *                xferrecv_buffer_processor -- caller-supplied function to
 *                                             be called when buffer full
 * Returns:       Number of bytes transferred on successful completion
 *                or -1 otherwise.
 * Other Info:    none.
 *
 */

int xferrecv_doimport(char *buf, int size, xferrecv_buffer_processor);

/*
 * int xferrecv_returnImportedBlock(flex_ptr p)
 *
 * Use
 *  Performs the data import if possible, and returns with the block filled
 *  with *ALL* the imported data i.e. it obviates the need of any work on
 *  your part for the data transfer.  This is the life, huh?  If anything
 *  went wrong, it returns -1 as for xferrecv_doimport
 *
 * Parameters
 *  flex_ptr p == flex pointer to nothing in particular (certainly not a
 *    flex block - one is allocated for you).  Remember to free it after
 *    you've read all the data!  Also ensure that flex has been initialised.
 *    If there is no data to import (i.e. the import failed) then p is freed
 *    of any data that may have been stored there.
 *
 * Returns
 *  -1 for failure, or the total size of the imported data for success
 */

int xferrecv_returnImportedBlock(flex_ptr p);

/* ---------------------- xferrecv_file_is_safe ----------------------------
 * Description:   Informs caller if file was recieved from a "safe" source
 *                (see below for definition of "safe").
 *
 * Parameters:    void
 * Returns:       true if file is safe.
 * Other Info:    "Safe" in this context means that the supplied filename
 *                will not change in the foreseeable future.
 *
 */

BOOL xferrecv_file_is_safe(void);

#endif

/* end xferrecv.h */