'\" te
.\" This manual page is derived from the DAT/uDAPL 1.2 specification.
.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
.TH dat_registry_list_providers 3DAT "16 Jul 2004" "SunOS 5.11" "Direct Access Transport Library Functions"
.SH NAME
dat_registry_list_providers \- obtain a list of available pProviders from the Static Registry
.SH SYNOPSIS
.LP
.nf
typedef struct dat_provider_info {
    char ia_name[DAT_NAME_MAX_LENGTH];
    DAT_UINT32      dapl_version_major;
    DAT_UINT32      dapl_version_minor;
    DAT_BOOLEAN     is_thread_safe;
    } DAT_PROVIDER_INFO;

cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ] 
#include <\fBdat/udat.h\fR>

DAT_RETURN
    dat_registry_list_providers (
    IN    DAT_COUNT          max_to_return,
    OUT   DAT_COUNT          *number_entries,
    OUT   DAT_PROVIDER_INFO  *(dat_provider_list[])
    )
.fi

.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fImax_to_return\fR\fR
.ad
.RS 21n
.rt  
Maximum number of entries that can be returned to the Consumer in the \fIdat_provider_list\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fInumber_entries\fR\fR
.ad
.RS 21n
.rt  
The actual number of entries returned to the Consumer in the \fIdat_provider_list\fR if successful or the number of Providers available.
.RE

.sp
.ne 2
.mk
.na
\fB\fIdat_provider_list\fR\fR
.ad
.RS 21n
.rt  
Points to an array of \fBDAT_PROVIDER_INFO\fR pointers supplied by the Consumer. Each Provider's information will be copied to the destination specified.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBdat_registry_list_providers()\fR function allows the Consumer to obtain a list of available Providers from the Static Registry. The information provided is the Interface Adapter name, the uDAPL/kDAPL API version supported, and whether the provided version is thread-safe. The Consumer can examine the attributes to determine which (if any) Interface Adapters it wants to open. This operation has no effect on the Registry itself.
.sp
.LP
The Registry can open an IA using a Provider whose \fIdapl_version_minor\fR is larger than the one the Consumer requests if no Provider entry matches exactly. Therefore, Consumers should expect that an IA can be opened successfully as long as at least one Provider entry returned by \fBdat_registry_list_providers()\fR matches the \fIia_name\fR, \fIdapl_version_major\fR, and \fIis_thread_safe\fR fields exactly, and has a \fIdapl_version_minor\fR that is equal to or greater than the version requested.
.sp
.LP
If the operation is successful, the returned value is \fBDAT_SUCCESS\fR and \fInumber_entries\fR indicates the number of entries filled by the registry in \fIdat_provider_list\fR.
.sp
.LP
If the operation is not successful, then \fInumber_entries\fR returns the number of entries in the registry. Consumers can use this return to allocate \fIdat_provider_list\fR large enough for the registry entries. This number is just a snapshot at the time of the call and may be changed by the time of the next call. If the operation is not successful, then the content of \fIdat_provider_list\fR is not defined.
.sp
.LP
If \fIdat_provider_list\fR is too small, including pointing to \fINULL\fR for the registry entries, then the operation fails with the return \fBDAT_INVALID_PARAMETER\fR.
.SH RETURN VALUES
.sp
.ne 2
.mk
.na
\fB\fBDAT_SUCCESS\fR\fR
.ad
.RS 25n
.rt  
The operation was successful.
.RE

.sp
.ne 2
.mk
.na
\fB\fBDAT_INVALID_PARAMETER\fR\fR
.ad
.RS 25n
.rt  
Invalid parameter. For example, \fIdat_provider_list\fR is too small or \fINULL\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fBDAT_INTERNAL_ERROR\fR\fR
.ad
.RS 25n
.rt  
Internal error. The DAT static registry is missing.
.RE

.SH USAGE
.sp
.LP
\fBDAT_NAME_MAX_LENGTH\fR includes the null character for string termination.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityCommitted
_
MT-LevelSafe
_
StandarduDAPL, 1.1, 1.2
.TE

.SH SEE ALSO
.sp
.LP
\fBlibdat\fR(3LIB), \fBattributes\fR(5)