chiark - git - mdw - ssr/blob - StraySrc/Libraries/Steel/h/xferrecv

   1 /****************************************************************************
   2  * This source file was written by Acorn Computers Limited. It is part of   *
   3  * the RISCOS library for writing applications in C for RISC OS. It may be  *
   4  * used freely in the creation of programs for Archimedes. It should be     *
   5  * used with Acorn's C Compiler Release 3 or later.                         *
   6  *                                                                          *
   7  ***************************************************************************/
   8
   9 /*----- Licensing note ----------------------------------------------------*
  10  *
  11  * This file is part of Straylight's Steel library.
  12  *
  13  * Steel is free software; you can redistribute it and/or modify
  14  * it under the terms of the GNU General Public License as published by
  15  * the Free Software Foundation; either version 2, or (at your option)
  16  * any later version.
  17  *
  18  * Steel is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU General Public License for more details.
  22  *
  23  * You should have received a copy of the GNU General Public License
  24  * along with Steel.  If not, write to the Free Software Foundation,
  25  * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  26  */
  27
  28 /* Title:   xferrecv.h
  29  * Purpose: general purpose import of data by dragging icon
  30  *
  31  */
  32
  33 #ifndef __xferrecv_h
  34 #define __xferrecv_h
  35
  36 #ifndef __flex_h
  37   #include "flex.h"
  38 #endif
  39
  40 #ifndef BOOL
  41 #define BOOL int
  42 #define TRUE 1
  43 #define FALSE 0
  44 #endif
  45
  46
  47 /* -------------------------- xferrecv_checkinsert -------------------------
  48  * Description:   Set up the acknowledge message for a MDATAOPEN or MDATALOAD
  49  *                and get filename to load from.
  50  *
  51  * Parameters:    char **filename -- returned pointer to filename
  52  * Returns:       the file's type (eg. 0x0fff for !Edit)
  53  * Other Info:    This function checks to see if the last wimp event was a
  54  *                request to import a file. If so it returns file type and
  55  *                a pointer to file's name is put into *filename. If not
  56  *                it returns -1.
  57  *
  58  */
  59
  60 int xferrecv_checkinsert(char **filename);
  61
  62
  63 /* --------------------------- xferrecv_insertfileok -----------------------
  64  * Description:   Deletes scrap file (if used for transfer), and sends
  65  *                acknowledgement of MDATALOAD message.
  66  *
  67  * Parameters:    void
  68  * Returns:       void.
  69  * Other Info:    none.
  70  *
  71  */
  72
  73 void xferrecv_insertfileok(void);
  74
  75
  76 /* --------------------------- xferrecv_checkprint -------------------------
  77  * Description:   Set up acknowledge message to a MPrintTypeOdd message
  78  *                and get file name to print.
  79  *
  80  * Parameters:    char **filename -- returned pointer to filename
  81  * Returns:       The file's type (eg. 0x0fff for !Edit).
  82  * Other Info:    Application can either print file directly or convert it to
  83  *                <Printer$Temp> for printing by the printer application.
  84  *
  85  */
  86
  87 int xferrecv_checkprint(char **filename);
  88
  89
  90 /* --------------------------- xferrecv_printfileok ------------------------
  91  * Description:   Send an acknowledgement back to printer application. If
  92  *                file sent to <Printer$Temp> then this also fills in file
  93  *                type in message.
  94  *
  95  * Parameters:    int type -- type of file sent to <Printer$Temp>
  96  *                            (eg. 0x0fff for !edit)
  97  * Returns:       void.
  98  * Other Info:    none.
  99  *
 100  */
 101
 102 void xferrecv_printfileok(int type);
 103
 104
 105 /* ---------------------------- xferrecv_checkimport -----------------------
 106  * Description:   Set up acknowledgement message to a MDATASAVE message.
 107  *
 108  * Parameters:    int *estsize -- sender's estimate of file size
 109  * Returns:       File type.
 110  * Other Info:    none.
 111  *
 112  */
 113
 114 int xferrecv_checkimport(int *estsize);
 115
 116 /*
 117  * char *xferrecv_nameToImport(void)
 118  *
 119  * Use
 120  *  Returns the name of the file to import (full pathname if available).
 121  *
 122  * Returns
 123  *  A pointer to a read-only string.
 124  */
 125
 126 char *xferrecv_nameToImport(void);
 127
 128 /*
 129  * void xferrecv_importByScrap(void)
 130  *
 131  * Use
 132  *  Tells xferrecv not to bother with RAM transfer, but to use the
 133  *  <Wimp$Scrap> file instead.  It checks that the system variables and
 134  *  everything are set up right beforehand.
 135  */
 136
 137 void xferrecv_importByScrap(void);
 138
 139 /* ------------------------- xferrecv_buffer_processor ---------------------
 140  * Description:   This is a typedef for the caller-supplied function
 141  *                to empty a full buffer during data transfer.
 142  *
 143  * Parameters:    char **buffer -- new buffer to be used
 144  *                int *size -- updated size
 145  * Returns:       return FALSE if unable to empty buffer or create new one.
 146  * Other Info:    This is the function (supplied by application,) which will
 147  *                be called when buffer is full. It should empty the current
 148  *                buffer, or create more space and modify size accordingly
 149  *                or return FALSE. *buffer and *size are the current buffer
 150  *                and its size on function entry.
 151  *
 152  */
 153
 154 typedef BOOL (*xferrecv_buffer_processor)(char **buffer, int *size);
 155
 156
 157
 158 /* ---------------------------- xferrecv_doimport --------------------------
 159  * Description:   Loads data into a buffer, and calls the caller-supplied
 160  *                function to empty the buffer when full.
 161  *
 162  * Parameters:    char *buf -- the buffer
 163  *                int size -- buffer's size
 164  *                xferrecv_buffer_processor -- caller-supplied function to
 165  *                                             be called when buffer full
 166  * Returns:       Number of bytes transferred on successful completion
 167  *                or -1 otherwise.
 168  * Other Info:    none.
 169  *
 170  */
 171
 172 int xferrecv_doimport(char *buf, int size, xferrecv_buffer_processor);
 173
 174 /*
 175  * int xferrecv_returnImportedBlock(flex_ptr p)
 176  *
 177  * Use
 178  *  Performs the data import if possible, and returns with the block filled
 179  *  with *ALL* the imported data i.e. it obviates the need of any work on
 180  *  your part for the data transfer.  This is the life, huh?  If anything
 181  *  went wrong, it returns -1 as for xferrecv_doimport
 182  *
 183  * Parameters
 184  *  flex_ptr p == flex pointer to nothing in particular (certainly not a
 185  *    flex block - one is allocated for you).  Remember to free it after
 186  *    you've read all the data!  Also ensure that flex has been initialised.
 187  *    If there is no data to import (i.e. the import failed) then p is freed
 188  *    of any data that may have been stored there.
 189  *
 190  * Returns
 191  *  -1 for failure, or the total size of the imported data for success
 192  */
 193
 194 int xferrecv_returnImportedBlock(flex_ptr p);
 195
 196 /* ---------------------- xferrecv_file_is_safe ----------------------------
 197  * Description:   Informs caller if file was recieved from a "safe" source
 198  *                (see below for definition of "safe").
 199  *
 200  * Parameters:    void
 201  * Returns:       true if file is safe.
 202  * Other Info:    "Safe" in this context means that the supplied filename
 203  *                will not change in the foreseeable future.
 204  *
 205  */
 206
 207 BOOL xferrecv_file_is_safe(void);
 208
 209 #endif
 210
 211 /* end xferrecv.h */