/* Copyright 1996 Acorn Computers Ltd
*
* Licensed 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.
*/
/****************************************************************************
* 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. *
* *
***************************************************************************/
/* Title: xfersend.h
* Purpose: general purpose export of data by dragging icon
*
*/
#ifndef __xfersend_h
#define __xfersend_h
#ifndef BOOL
#define BOOL int
#define TRUE 1
#define FALSE 0
#endif
#ifndef __wimp_h
#include "wimp.h"
#endif
/******************* CALLER-SUPPLIED FUNCTION TYPES ************************/
/* ------------------------ xfersend_saveproc ------------------------------
* Description: A function of this type should save to the given file and
* return TRUE if successful. Handle is passed to the
* function by xfersend().
*
* Parameters: char *filename -- file to be saved
* void *handle -- the handle you passed to xfersend()
* Returns: The function must return TRUE if save was successful.
* Other Info: none.
*
*/
typedef BOOL (*xfersend_saveproc)(char *filename, void *handle);
/* ----------------------- xfersend_sendproc -------------------------------
* Description: A function of this type should call xfersend_sendbuf()
* to send one "buffer-full" of data no bigger than
* *maxbuf.
*
* Parameters: void *handle -- handle which was passed to xfersend
* int *maxbuf -- size of receiver's buffer
* Returns: The function must return TRUE if data was successfully
* transmitted.
* Other Info: Note: Your sendproc will be called by functions in the
* xfersend module to do an in-core data transfer, on
* receipt of MRAMFetch messages from the receiving
* application. If xfersend_sendbuf() returns FALSE, then
* return FALSE **IMMEDIATELY**.
*
*/
typedef BOOL (*xfersend_sendproc)(void *handle, int *maxbuf);
/* --------------------------- xfersend_printproc --------------------------
* Description: A function of this type should either print the file
* directly, or save it into the given filename, from
* where it will be printed by the printer application.
*
* Parameters: char *filename -- file to save into, for printing
* void *handle -- handle that was passed to xfersend()
* Returns: The function should return either the file type of the
* file it saved, or one of the reason codes #defined below.
*
* Other Info: This is called if the file icon has been dragged onto a
* printer application.
*
*/
typedef int (*xfersend_printproc)(char *filename, void *handle);
#define xfersend_printPrinted -1 /* file dealt with internally */
#define xfersend_printFailed -2 /* had an error along the way */
/* The saveproc should report any errors it encounters itself. If saving
to a file, it should convert the data into a type that can be printed by
the printer application (i.e. text). */
/*************************** LIBRARY FUNCTIONS *****************************/
/* ----------------------------- xfersend ----------------------------------
* Description: Allows the user to export application data, by icon drag.
*
* Parameters: int filetype -- type of file to save to
* char *name -- suggested file name
* int estsize -- estimated size of the file
* xfersend_saveproc -- caller-supplied function for saving
* application data to a file
* xfersend_sendproc -- caller-supplied function for in-core
* data transfer (if application is able
* to do this)
* xfersend_printproc -- caller-supplied function for printing
* application data, if "icon" is
* dragged onto printer application
* wimp_eventstr *e -- the event which started the export
* (usually mouse drag)
* void *handle -- handle to be passed to handler functions.
* Returns: TRUE if data exported successfully.
* Other Info: You should typically call this function in a window's
* event handler, when you get a "mouse drag" event.
* See the "saveas.c" code for an example of this.
* xfersend deals with the complexities of message-passing
* protocols to achieve the data transfer. Refer to the above
* typedefs for an explanation of what the three
* caller-supplied functions should do.
* If "name" is 0 then a default name of "Selection" is
* supplied.
* If you pass 0 as the xfersend_sendproc, then no in-core
* data transfer will be attempted
* If you pass 0 as the xfersend_printproc, then the file
* format for printing is assumed to be the same as for saving
* The estimated file size is not essential, but may improve
* performance.
*
*/
BOOL xfersend(int filetype, char *name, int estsize,
xfersend_saveproc, xfersend_sendproc, xfersend_printproc,
wimp_eventstr *e, void *handle);
/* ----------------------------- xfersend_print ----------------------------
* Description: Starts the file transfer protocol to the printer driver
* (if one is loaded)
*
* Parameters: int filetype -- type of file to print
* char *name -- suggested file name
* int estsize -- estimated size of the file
* xfersend_saveproc -- caller-supplied function for saving
* application data to a file
* xfersend_sendproc -- caller-supplied function for in-core
* data transfer (if application is able
* to do this)
* xfersend_printproc -- caller-supplied function for printing
* application data, if required
* void *handle -- handle to be passed to handler functions.
*
* Returns: TRUE if data queued successfully.
*
* Other Info: Call this function if you want to print something as the
* result of an action of the user. Xfersend_print() deals
* with the complexities of message-passing protocols to
* achieve the data transfer. There are two possibilities:
* (j) The data is queued by the printer manager for later
* printing - you will get a Message_PrintTypeOdd when it
* wants the printing to be done; or (ij) the printer driver
* demands instant printing, or is not loaded: then this
* function will call the xfersend_printproc to print the
* data immediately. Refer to the above typedefs for an
* explanation of what the two caller-supplied functions
* should do.
* If "name" is 0 then a default name of "Selection" is
* supplied.
* If you pass 0 as the xfersend_sendproc, then no in-core
* data transfer will be attempted
* If you psss 0 as the printproc, it is assumed that you
* cannot print the file yourself. The printer manager will copy
* the file and try to print it using the normal protocol.
* The estimated file size is not essential, but may
* improve performance.
*/
BOOL xfersend_print (int filetype, char *name, int estsize,
xfersend_saveproc, xfersend_sendproc, xfersend_printproc, void *handle);
/* ----------------------------- xfersend_pipe -----------------------------
* Description: Allows the user to export application data, without an
* icon drag.
*
* Parameters: int filetype -- type of file to save to
* char *name -- suggested file name
* int estsize -- estimated size of the file
* xfersend_saveproc -- caller-supplied function for saving
* application data to a file
* xfersend_sendproc -- caller-supplied function for in-core
* data transfer (if application is able
* to do this)
* xfersend_printproc -- caller-supplied function for printing
* application data, if "icon" is
* dragged onto printer application
* void *handle -- handle to be passed to handler functions.
* wimp_t task - handle of task to pass data to.
* Returns: TRUE if data exported successfully.
* Other Info: This function works similarly to xfersend, except it is
* not normally used as the result of an icon drag.
* Typical use may be to export data to another application
* (using the same technique as xfersend), following a
* request for data from that application (maybe as a result
* of receiving an application-specific wimp message).
*
*/
BOOL xfersend_pipe(int filetype, char *name, int estsize,
xfersend_saveproc, xfersend_sendproc, xfersend_printproc,
void *handle, wimp_t task);
/* ------------------------ xfersend_sendbuf -------------------------------
* Description: Sends the given buffer to a receiver.
*
* Parameters: char *buffer -- the buffer to be sent
* int size -- the number of characters placed in the buffer
* Returns: TRUE if send was successful.
* Other Info: This function should be called by the caller-supplied
* xfersend_sendproc (if such exists) to do in-core data
* transfer (see notes on xfersend_sendproc above).
*
*/
BOOL xfersend_sendbuf(char *buffer, int size);
/* ------------------------ xfersend_file_is_safe --------------------------
* Description: Informs caller if the file's name can be reliably assumed
* not to change (during data transfer!!)
*
* Parameters: void
* Returns: TRUE if file is "safe".
* Other Info: See also the xferrecv module.
*
*/
BOOL xfersend_file_is_safe(void) ;
/* Returns TRUE if file recipient will not modify it; changing the
window title of the file can be done conditionally on this result. This
can be called within your xfersend_saveproc,sendproc, or printproc,
or immediately after the main xfersend. */
/* ---------------------------- xfersend_set_fileissafe --------------------
* Description: Allows caller to set an indication of whether a file's
* name will remain unchanged during data transfer.
*
* Parameters: BOOL value -- TRUE means file is safe.
* Returns: void.
* Other Info: none.
*
*/
void xfersend_set_fileissafe(BOOL value);
/* --------------------------- xfersend_close_on_xfer ----------------------
* Description: Tells xfersend whether to close "parent" window after
* icon-drag export.
*
* Parameters: BOOL do_we_close -- TRUE means close window after export.
* wimp_w w -- handle of window to close (presumably "parent"
* window.
* Returns: void.
* Other Info: The default is to not close the window after export.
* Once used, this function should be called before each
* call to xfersend().
*
*/
void xfersend_close_on_xfer(BOOL do_we_close, wimp_w w);
/* --------------------------- xfersend_clear_unknowns ----------------------
* Description: Removes any unknown event processors registered by xfersend
* or xfersend_pipe.
*
* Parameters: void.
* Returns: void.
* Other Info: xfersend and xfersend_pipe use unknown event processors to
* deal with inter-application data transfer. These may be
* left around after completion of the transfer (especially if
* the transfer failed). This function should be called when it
* is known that the transfer has ended.
*
*/
void xfersend_clear_unknowns(void);
/* --------------------------- xfersend_read_last_ref -----------------------
* Description: Returns the my_ref value of the last wimp_MDATASAVE or
* wimp_MDATALOAD message sent by xfersend or xfersend_pipe.
*
* Parameters: void.
* Returns: integer message reference
* Other Info: After saving a file to another application (ie. where the
* resulting file is not 'safe', the my_ref value of the
* final wimp_MDATALOAD should be stored with the document
* data, so that if a wimp_MDATASAVED is received, the
* document can be marked unmodified. If the document is
* modified after being saved, the last_ref value should be
* reset to 0, so that a subsequent wimp_MDATASAVED message
* will not cause the document to be marked unmodified.
* NB: If RAM transfer is used, the my_ref of the datasave
* message should be stored instead.
*/
int xfersend_read_last_ref(void);
#endif
/* end xfersend.h */