.TH "globus_gass_transfer_referral" 3 "Tue Jul 5 2022" "Version 9.4" "globus_gass_transfer" \" -*- nroff -*-
.ad l
.nh
.SH NAME
globus_gass_transfer_referral \- Referrals
.PP
 \- GASS Referrals\&.  

.SH SYNOPSIS
.br
.PP
.SS "Functions"

.in +1c
.ti -1c
.RI "globus_size_t \fBglobus_gass_transfer_referral_get_count\fP (globus_gass_transfer_referral_t *referral)"
.br
.ti -1c
.RI "char * \fBglobus_gass_transfer_referral_get_url\fP (globus_gass_transfer_referral_t *referral, globus_size_t index)"
.br
.ti -1c
.RI "int \fBglobus_gass_transfer_referral_destroy\fP (globus_gass_transfer_referral_t *referral)"
.br
.in -1c
.SH "Detailed Description"
.PP 
GASS Referrals\&. 

Referrals
.PP
The GASS Transfer API supports referring URL requests to alternate URLs via referrals\&. Referrals are essentially pointers to another URL or URLs which contain the same file as the original location which a client has requested of a server\&. Referrals may span multiple protocol schemes, though not all protocols may be able to generate referrals\&. For example, an HTTP server may refer a client to another HTTP server, an HTTPS server\&.
.PP
Upon receiving a referred response from a server, a client should query the request handle to determine from where the file can be retrieved\&. 
.SH "Function Documentation"
.PP 
.SS "int globus_gass_transfer_referral_destroy (globus_gass_transfer_referral_t * referral)"
Free all memory used by a referral\&.
.PP
This function frees all memory used by this referral\&. After calling this function, the strings returned by calling \fBglobus_gass_transfer_referral_get_url()\fP must not be accessed\&. Any further attempts to extract informatoin from this referral will fail\&.
.PP
\fBParameters\fP
.RS 4
\fIreferral\fP The referral to destroy\&.
.RE
.PP
\fBReturn values\fP
.RS 4
\fIGLOBUS_SUCCESS\fP The referral was successfully destroyed\&. 
.br
\fIGLOBUS_GASS_TRANSFER_ERROR_NULL_POINTER\fP The referral parameter was GLOBUS_NULL\&. It could not be destroyed\&. 
.RE
.PP

.SS "globus_size_t globus_gass_transfer_referral_get_count (globus_gass_transfer_referral_t * referral)"
Get the number of URLs in this referral\&.
.PP
This function examines the referral to determine if the number of URLs which are contained in it\&. Each of these URLs should either point to another referral, or to a URL containing the equivalent file as the original URL request which caused this referral\&.
.PP
\fBParameters\fP
.RS 4
\fIreferral\fP The referral structure to query\&.
.RE
.PP
\fBReturns\fP
.RS 4
This function returns the number of URL entries in the referral, or 0, if there are none\&. 
.RE
.PP

.SS "char* globus_gass_transfer_referral_get_url (globus_gass_transfer_referral_t * referral, globus_size_t index)"
Get a URL string from a referral\&.
.PP
This function examines the referral to retrieve a URL string from it\&. A valid referal will contain one or more strings\&. They are indexed from 0 to the value returned by \fBglobus_gass_transfer_referral_get_count()\fP - 1\&.
.PP
The string returned by this function must not be freed by the caller\&. It will remain valid until the referral structure is destroyed\&.
.PP
\fBParameters\fP
.RS 4
\fIreferral\fP The referral structure to query\&.
.br
\fIindex\fP The URL to extract from the referral\&. 
.RE
.PP
\fBReturns\fP
.RS 4
This function returns a string pointer containing the URL, or NULL if the index or referral were invalid\&. 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for globus_gass_transfer from the source code\&.