2
* Copyright 1999-2006 University of Chicago
4
* Licensed under the Apache License, Version 2.0 (the "License");
5
* you may not use this file except in compliance with the License.
6
* You may obtain a copy of the License at
8
* http://www.apache.org/licenses/LICENSE-2.0
10
* Unless required by applicable law or agreed to in writing, software
11
* distributed under the License is distributed on an "AS IS" BASIS,
12
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
* See the License for the specific language governing permissions and
14
* limitations under the License.
19
* Header file for the gass copy library
25
* The Globus GASS Copy library is motivated by the desire to provide a
26
* uniform interface to transfer files specified by different protocols.
28
* The goals in doing this are to:
30
* - Provide a robust way to describe and apply file transfer properties
31
* for a variety of protocols. These include the standard HTTP, FTP and
32
* GSIFTP options. Some of the new file transfer capabilities in GSIFTP are
33
* parallel, striping, authentication and TCP buffer sizing.
34
* - Provide a service to support nonblocking file transfer and handle
35
* asynchronous file and network events.
36
* - Provide a simple and portable way to implement file transfers.
38
* Any program that uses Globus GASS Copy functions must include
39
* "globus_gass_copy.h".
42
* <a href="main.html" target="_top">View documentation without frames</a><br>
43
* <a href="index.html" target="_top">View documentation with frames</a><br>
47
#include "globus_gass_transfer.h"
48
#include "globus_ftp_client.h"
49
#include "globus_io.h"
51
#ifndef GLOBUS_INCLUDE_GLOBUS_GASS_COPY_H
52
#define GLOBUS_INCLUDE_GLOBUS_GASS_COPY_H
54
#ifndef EXTERN_C_BEGIN
56
#define EXTERN_C_BEGIN extern "C" {
57
#define EXTERN_C_END }
59
#define EXTERN_C_BEGIN
71
* Globus GASS Copy uses standard Globus module activation and deactivation.
72
* Before any Globus GASS Copy functions are called, the following function
76
* globus_module_activate(GLOBUS_GASS_COPY_MODULE)
80
* This function returns GLOBUS_SUCCESS if Globus GASS Copy was successfully
81
* initialized, and you are therefore allowed to subsequently call
82
* Globus GASS Copy functions. Otherwise, an error code is returned, and
83
* Globus GASS Copy functions should not be subsequently called. This
84
* function may be called multiple times.
86
* To deactivate Globus GASS Copy, the following function must be called:
89
* globus_module_deactivate(GLOBUS_GASS_COPY_MODULE)
92
* This function should be called once for each time Globus GASS Copy was
96
#define GLOBUS_GASS_COPY_MODULE (&globus_i_gass_copy_module)
99
globus_module_descriptor_t globus_i_gass_copy_module;
101
#define _GASCSL(s) globus_common_i18n_get_string( \
102
GLOBUS_GASS_COPY_MODULE, \
106
typedef struct globus_gass_copy_state_s globus_gass_copy_state_t;
107
typedef struct globus_gass_copy_handle_s globus_gass_copy_handle_t;
108
typedef struct globus_gass_copy_perf_info_s globus_gass_copy_perf_info_t;
111
* Gass copy transfer performance callback
113
* This callback is registered with 'globus_gass_copy_register_performance_cb'
114
* It will be called during a transfer to supply performance information on
115
* current transfer. Its frequency will be at most one per second, but
116
* it is possible to receive no callbacks. This is possible in very short
117
* transfers and in ftp transfers in which the server does not provide
118
* performance information.
121
* the gass copy handle this transfer is occurring on
124
* a user pointer registered with
125
* 'globus_gass_copy_register_performance_cb'
128
* the total number of bytes transfer so far
130
* @param instantaneous_throughput
131
* instantaneous rate of transfer (since last callback or start)
134
* @param avg_throughput
135
* the avg thoughput calculated since the start of the transfer
141
typedef void (*globus_gass_copy_performance_cb_t)(
143
globus_gass_copy_handle_t * handle,
144
globus_off_t total_bytes,
145
float instantaneous_throughput,
146
float avg_throughput);
148
#ifndef GLOBUS_DONT_DOCUMENT_INTERNAL
151
* Signature of a callback from globus_gass_copy_register_*() functions.
152
* (asynchronous transfer functions)
154
typedef void (*globus_gass_copy_callback_t)(
156
globus_gass_copy_handle_t * handle,
157
globus_object_t * error);
160
* valid state status (aka states)
164
GLOBUS_GASS_COPY_STATUS_NONE,
165
GLOBUS_GASS_COPY_STATUS_PENDING,
166
GLOBUS_GASS_COPY_STATUS_INITIAL,
167
GLOBUS_GASS_COPY_STATUS_SOURCE_READY,
168
GLOBUS_GASS_COPY_STATUS_TRANSFER_IN_PROGRESS,
169
GLOBUS_GASS_COPY_STATUS_READ_COMPLETE,
170
GLOBUS_GASS_COPY_STATUS_WRITE_COMPLETE,
171
GLOBUS_GASS_COPY_STATUS_DONE,
172
GLOBUS_GASS_COPY_STATUS_FAILURE,
173
GLOBUS_GASS_COPY_STATUS_CANCEL,
174
GLOBUS_GASS_COPY_STATUS_DONE_SUCCESS,
175
GLOBUS_GASS_COPY_STATUS_DONE_FAILURE,
176
GLOBUS_GASS_COPY_STATUS_DONE_CANCELLED
177
} globus_gass_copy_status_t;
184
GLOBUS_GASS_COPY_URL_MODE_UNSUPPORTED,
185
GLOBUS_GASS_COPY_URL_MODE_FTP,
186
GLOBUS_GASS_COPY_URL_MODE_GASS,
187
GLOBUS_GASS_COPY_URL_MODE_IO
188
} globus_gass_copy_url_mode_t;
193
struct globus_gass_copy_handle_s
196
* the status of the current transfer
198
globus_gass_copy_status_t status;
201
* pointer to the state structure which contains internal info related to a
204
globus_gass_copy_state_t * state;
207
* pointer to user data
211
/* pointer to perf_info structure used to provide the user transfer
212
* performance information
214
globus_gass_copy_perf_info_t * performance;
217
* indicates if the 3rd party transfer is done by this library or externally
220
globus_bool_t external_third_party;
223
* pointer to user callback function
225
globus_gass_copy_callback_t user_callback;
228
* pointer to user argument to user callback function
233
* pointer to user cancel callback function
235
globus_gass_copy_callback_t user_cancel_callback;
238
* pointer to user argument to user cancel callback function
240
void * cancel_callback_arg;
243
* Error object to pass to the callback function
245
globus_object_t * err;
248
* size of the buffers to be used in the transfers
253
* says whether third_party transfers should be used (for ftp to
254
* ftp transfers). if set to FALSE, the default,
255
* globus_ftp_client_third_party_transfer() will be used. if set to
256
* TRUE, gass_copy will manage the transfer
258
globus_bool_t no_third_party_transfers;
260
globus_ftp_client_handle_t ftp_handle;
261
/* this handle only used when no_third_party_transfers is true (for 3pt) */
262
globus_ftp_client_handle_t ftp_handle_2;
264
/* offsets for partial file transfers */
265
globus_off_t partial_offset;
266
globus_off_t partial_end_offset;
267
globus_off_t partial_bytes_remaining;
269
/* says whether or not to send ALLO for ftp destinations */
270
globus_bool_t send_allo;
272
/* run a stat check on all urls passed to globus_gass_copy_glob_expand_url */
273
globus_bool_t always_stat_on_expand;
277
* GASS Copy attribute structure. Contains any/all attributes that are
278
* required to perform the supported transfer methods (ftp, gass, io).
280
typedef struct globus_gass_copy_attr_s
282
globus_ftp_client_operationattr_t * ftp_attr;
283
globus_io_attr_t * io;
284
globus_gass_transfer_requestattr_t * gass_requestattr;
285
} globus_gass_copy_attr_t;
288
* GASS Copy Handle attribute structure. Contains any/all attributes that
289
* are required to create lower-level handles (ftp, gass, io).
291
typedef struct globus_gass_copy_handleattr_s
293
globus_ftp_client_handleattr_t * ftp_attr;
294
} globus_gass_copy_handleattr_t;
296
/** initialization and destruction of GASS Copy handle */
298
globus_gass_copy_handle_init(
299
globus_gass_copy_handle_t * handle,
300
globus_gass_copy_handleattr_t * handle_attr);
303
globus_gass_copy_handle_destroy(
304
globus_gass_copy_handle_t * handle);
307
globus_gass_copy_handleattr_init(
308
globus_gass_copy_handleattr_t * handle_attr);
311
globus_gass_copy_handleattr_destroy(
312
globus_gass_copy_handleattr_t * handle_attr);
315
globus_gass_copy_handleattr_set_ftp_attr(
316
globus_gass_copy_handleattr_t * handle_attr,
317
globus_ftp_client_handleattr_t * ftp_attr);
319
/** set the size of the buffer to be used for the transfers */
321
globus_gass_copy_set_buffer_length(
322
globus_gass_copy_handle_t * handle,
325
/** get the size of the buffer being used for the transfers */
327
globus_gass_copy_get_buffer_length(
328
globus_gass_copy_handle_t * handle,
331
/** sets whether third_party transfers should be used for ftp to
334
globus_gass_copy_set_no_third_party_transfers(
335
globus_gass_copy_handle_t * handle,
336
globus_bool_t no_third_party_transfers);
338
/** get the size of the buffer being used for the transfers */
340
globus_gass_copy_get_no_third_party_transfers(
341
globus_gass_copy_handle_t * handle,
342
globus_bool_t * no_third_party_transfers);
344
/** get offsets for partial file transfer */
346
globus_gass_copy_get_partial_offsets(
347
globus_gass_copy_handle_t * handle,
348
globus_off_t * offset,
349
globus_off_t * end_offset);
351
/** set offsets for partial file transfer */
353
globus_gass_copy_set_partial_offsets(
354
globus_gass_copy_handle_t * handle,
356
globus_off_t end_offset);
358
/* send ALLO to ftp destinations */
360
globus_gass_copy_set_allocate(
361
globus_gass_copy_handle_t * handle,
362
globus_bool_t send_allo);
365
/* run a stat check on all urls passed to globus_gass_copy_glob_expand_url
370
globus_gass_copy_set_stat_on_expand(
371
globus_gass_copy_handle_t * handle,
372
globus_bool_t always_stat);
375
/* find out what transfer mode will be used for a given url, so that the proper attributes may be passed to one of the copy function */
377
globus_gass_copy_get_url_mode(
379
globus_gass_copy_url_mode_t * mode);
381
/* get current ftp client handle -- use with care if modifying the handle */
383
globus_gass_copy_get_ftp_handle(
384
globus_gass_copy_handle_t * handle,
385
globus_ftp_client_handle_t * ftp_handle);
387
/** initialize the attr structure */
389
globus_gass_copy_attr_init(
390
globus_gass_copy_attr_t * attr);
392
/** functions for setting attributes for specific protocols */
394
globus_gass_copy_attr_set_ftp(
395
globus_gass_copy_attr_t * attr,
396
globus_ftp_client_operationattr_t * ftp_attr);
399
globus_gass_copy_attr_set_io(
400
globus_gass_copy_attr_t * attr,
401
globus_io_attr_t * io_attr);
404
globus_gass_copy_attr_set_gass(
405
globus_gass_copy_attr_t * attr,
406
globus_gass_transfer_requestattr_t * gass_attr);
409
* copy functions (blocking)
412
globus_gass_copy_url_to_url(
413
globus_gass_copy_handle_t * handle,
415
globus_gass_copy_attr_t * source_attr,
417
globus_gass_copy_attr_t * dest_attr);
420
globus_gass_copy_url_to_handle(
421
globus_gass_copy_handle_t * handle,
423
globus_gass_copy_attr_t * source_attr,
424
globus_io_handle_t * dest_handle);
427
globus_gass_copy_handle_to_url(
428
globus_gass_copy_handle_t * handle,
429
globus_io_handle_t * source_handle,
431
globus_gass_copy_attr_t * dest_attr);
434
* copy functions (asyncronous)
437
globus_gass_copy_register_url_to_url(
438
globus_gass_copy_handle_t * handle,
440
globus_gass_copy_attr_t * dest_attr,
442
globus_gass_copy_attr_t * source_attr,
443
globus_gass_copy_callback_t callback_func,
444
void * callback_arg);
447
globus_gass_copy_register_url_to_handle(
448
globus_gass_copy_handle_t * handle,
450
globus_gass_copy_attr_t * source_attr,
451
globus_io_handle_t * dest_handle,
452
globus_gass_copy_callback_t callback_func,
453
void * callback_arg);
456
globus_gass_copy_register_handle_to_url(
457
globus_gass_copy_handle_t * handle,
458
globus_io_handle_t * source_handle,
460
globus_gass_copy_attr_t * dest_attr,
461
globus_gass_copy_callback_t callback_func,
462
void * callback_arg);
465
* get the status code of the current transfer
468
globus_gass_copy_get_status(
469
globus_gass_copy_handle_t * handle,
470
globus_gass_copy_status_t *status);
473
* get the status string of the current transfer
477
globus_gass_copy_get_status_string(
478
globus_gass_copy_handle_t * handle);
481
* cancel the current transfer
484
globus_gass_copy_cancel(
485
globus_gass_copy_handle_t * handle,
486
globus_gass_copy_callback_t cancel_callback,
487
void * cancel_callback_arg);
490
* cache handles functions
492
* Use this when transferring mulitple files from or to the same host
495
globus_gass_copy_cache_url_state(
496
globus_gass_copy_handle_t * handle,
500
globus_gass_copy_flush_url_state(
501
globus_gass_copy_handle_t * handle,
505
* get/set user pointers from/to GASS Copy handles
508
globus_gass_copy_set_user_pointer(
509
globus_gass_copy_handle_t * handle,
513
globus_gass_copy_get_user_pointer(
514
globus_gass_copy_handle_t * handle,
518
globus_gass_copy_register_performance_cb(
519
globus_gass_copy_handle_t * handle,
520
globus_gass_copy_performance_cb_t callback,
524
* Set Attribute functions
528
/* TCP buffer/window size */
530
globus_gass_copy_attr_set_tcpbuffer(
531
globus_gass_copy_attr_t * attr,
532
globus_ftp_control_tcpbuffer_t * tcpbuffer_info);
534
/* parallel transfer options */
536
globus_gass_copy_attr_set_parallelism(
537
globus_gass_copy_attr_t * attr,
538
globus_ftp_control_parallelism_t * parallelism_info);
540
/* striping options */
542
globus_gass_copy_attr_set_striping(
543
globus_gass_copy_attr_t * attr,
544
globus_ftp_control_striping_t * striping_info);
546
/* authorization options */
548
globus_gass_copy_attr_set_authorization(
549
globus_gass_copy_attr_t * attr,
550
globus_io_authorization_t * authorization_info);
552
/* secure channel options */
554
globus_gass_copy_attr_set_secure_channel(
555
globus_gass_copy_attr_t * attr,
556
globus_io_secure_channel_t * secure_channel_info);
559
#endif /* GLOBUS_DONT_DOCUMENT_INTERNAL */
562
* globbed entry types
565
GLOBUS_GASS_COPY_GLOB_ENTRY_UNKNOWN,
566
GLOBUS_GASS_COPY_GLOB_ENTRY_FILE,
567
GLOBUS_GASS_COPY_GLOB_ENTRY_DIR,
568
GLOBUS_GASS_COPY_GLOB_ENTRY_OTHER
569
} globus_gass_copy_glob_entry_t;
572
* Glob expanded entry information
576
/** The file type of the entry
578
globus_gass_copy_glob_entry_t type;
580
/** A string that uniquely identifies the data that the entry
581
* refers to. A file and a symlink to that file will have the
583
* It is NULL for when not available.
587
/** This points to the full path of the target of a symlink.
588
* It is NULL for non-symlinks or when not available.
590
char * symlink_target;
592
/** An integer specifying the mode of the file.
593
* It is set to -1 when not available.
597
/** An integer specifying the modification time of the file.
598
* It is set to -1 when not available.
602
/** A globus_off_t specifying the size of the file.
603
* It is set to -1 when not available.
606
} globus_gass_copy_glob_stat_t;
609
* Gass copy glob entry callback
611
* This callback is passed as a parameter to globus_gass_copy_glob_expand_url().
612
* It is called once for each entry that the original expands to.
615
* The full url to the expanded entry. A directory entry will end
616
* in a forward slash '/'.
619
* A pointer to a globus_gass_copy_glob_stat_t containing information
623
* The user_arg passed to globus_gass_copy_glob_expand()
625
* @see globus_gass_copy_glob_stat_t,
626
* globus_gass_copy_glob_expand_url
628
typedef void (*globus_gass_copy_glob_entry_cb_t)(
630
const globus_gass_copy_glob_stat_t * info_stat,
636
* This function expands wildcards in a globbed url, and calls
637
* entry_cb() on each one.
640
* A gass copy handle to use for the operation.
643
* The URL to expand. The URL may be an ftp, gsiftp or file URL.
644
* Wildcard characters supported are '?' '*' '[ ]' in the filename
645
* portion of the url.
648
* Gass copy attributes for this operation.
651
* Function to call with information about each entry
654
* An argument to pass to entry_cb()
657
* This function returns an error when any of these conditions are
659
* - handle is GLOBUS_NULL
660
* - url is GLOBUS_NULL
661
* - url cannot be parsed
662
* - url is not a ftp, gsiftp or file url
665
globus_gass_copy_glob_expand_url(
666
globus_gass_copy_handle_t * handle,
668
globus_gass_copy_attr_t * attr,
669
globus_gass_copy_glob_entry_cb_t entry_cb,
675
* This function creates a directory given a ftp or file url.
678
* A gass copy handle to use for the mkdir operation.
680
* The URL for the directory to create. The URL may be an ftp,
681
* gsiftp or file URL.
683
* Gass copy attributes for this operation.
686
* This function returns an error when any of these conditions are
688
* - handle is GLOBUS_NULL
689
* - url is GLOBUS_NULL
690
* - url cannot be parsed
691
* - url is not a ftp, gsiftp or file url
692
* - the directory could not be created
695
globus_gass_copy_mkdir(
696
globus_gass_copy_handle_t * handle,
698
globus_gass_copy_attr_t * attr);
701
globus_gass_copy_cksm(
702
globus_gass_copy_handle_t * handle,
704
globus_gass_copy_attr_t * attr,
707
const char * algorithm,
711
globus_gass_copy_cksm_async(
712
globus_gass_copy_handle_t * handle,
714
globus_gass_copy_attr_t * attr,
717
const char * algorithm,
719
globus_gass_copy_callback_t callback,
720
void * callback_arg);
723
globus_gass_copy_stat(
724
globus_gass_copy_handle_t * handle,
726
globus_gass_copy_attr_t * attr,
727
globus_gass_copy_glob_stat_t * stat_info);
732
#endif /* GLOBUS_INCLUDE_GLOBUS_GASS_COPY_H */