Function WSAStartup

Functia WSAStartup() din interfata Windows Sockets  se foloseste pentru initializarea utilizarii bibliotecii DLL de catre un proces.

Sintaxa

int WSAStartup (

WORD wVersionRequested, 
LPWSADATA lpWSAData 
);

unde:

• wVersionRequested - [in] Cea mai mare versiune a Windows Sockets pe care apelantul o poate utiliza. Octetul de ordin superior specifica numarul minor al versiunii (revizia), iar octetul de ordin inferior precizeaza numarul major al versiunii.
• lpWSAData - [out] un pointer catre o structura de date WSADATA care va primi detaliile referitoare la implementarea Windows Sockets.

Aceasta functie trebuie sa fie prima functie apelata de o aplicatie sau DLL. Ea permite unei aplicatii sa precizeze versiunea Windows Sockets necesara si sa obtina detalii referitor la implementarea Windows Sockets.

Detalii referitoare la implementarea reala a Windows Sockets sunt descrise in structura WSAData definita astfel:

struct WSAData {
WORD wVersion;
WORD wHighVersion;
char 
szDescription[WSADESCRIPTION_LEN+1];
char szSystemStatus[WSASYSSTATUS_LEN+1];
unsigned short iMaxSockets;
unsigned short iMaxUdpDg; 
char FAR * lpVendorInfo;
};

Membrii acestei structuri sunt:

• wVersion - Versiunea specificatiilor Windows Sockets pe care DLL-ul Windows Sockets se asteapta sa le foloseasca aplicatia care a factut apelul.
• wHighVersion - Ce amai mare versiune a specificatiilor Windows Sockets pe care caest DLL o poate suporta. De regula aceasta va fi aceeasi cu versiunea wVersion.
• sz - Un sir terminat cu zero in care DLL Windows Sockets DLL va copia descrierea implementarii Windows Sockets. Textul (de pana la 256 caractere) poate contine orice caracter in afara caracterelor de control si de formatare: cea mai probabila utilizare pe care o aplicatie o poate da cestei informatii este s-o afiseze (posibil trunchiata) intr-un mesaj de stare.
• szSystemStatus - Un sir ASCII terminat cu zero in care DLL-ul Windows Sockets va copia informatii relevante referitor la stare si configurare. DLL-ul Windows Sockets DLL trebuie sa utilizeze acest camp numai daca informatia poate fi utila utilizatorului sau personalului de asistenta tehnica: el nu trebuie considerat ca o extensie a campului szDescription.
• iMaxSockets - Acest camp este mentinut pentru compatibilitatea cu versiunile mai vechi, dar trebuie ignorat pentru versiunile mai mari ca 2 deoarece nici o singura valoare nu poate fi potrivita pentru toti furnizorii de servici subsumati.
• iMaxUdpDg - Aceasta valoare trebuie ignorata pentru versiuni mai noi de 2.0. Ea este retinuta pentru compatibiliate cu specificatia Windows Sockets 1.1, dar trebuie sa nu fie folosita cand se dezvolta aplicatii noi. Pentru a afla dimensiunea reala a mesajului maxim specific unui furnizor particular de servicii Windows in cazul unui anume tip de socket, aplicatiile trebuie sa utilizeze functia getsockopt() pentru a afla valoarea optiunii SO_MAX_MSG_SIZE, dupa ce un socket a fost creat.
• lpVendorInfo - Aceasta valoare trebuie sa fie ignorata pentru versiuni mai noi de 2.0. Si ea este retinuta pentru compatibilitate cu specificatiile Windows Sockets 1.1. Aplicatiile care necesita accesul la informatii de configurare ce depind de vanzator trebuie sa foloseasca functia getsockopt pentru a obtine valuarea optiunii PVD_CONFIG. Definitia acestei valori (daca este utilizata) depaseste domeniul acestei specificatii.

O aplicatie sau DLL poate apela functia WSAStartup() de mai multe ori daca are nevoie sa obtina informatii din structura WSAData de mai multe ori. la fiecare astfel de apel aplicatia poate specifica orice numar de versiune suportat de catre DLL.

Trebuie sa exista cate un apel al functiei WSACleanup() pentru fiecare apel reusit al functiei WSAStartup pentru permite unei aplicatii sa foloseasca un DLL Windows Sockets. Aceasta inseamna, de exemplu, ca daca o aplicatie apeleaza de trei ori WSAStartup, ea trebuie sa apeleze WSACleanup() tot de trei ori. Primele doua apeluri ale WSACleanup() nu fac nimic altceva decat sa decrementeze un contor intern. Ultimul apel WSACleanup() va efectua toate dealocarile de resurse necesare.

Valoare returnata

Functia WSAStartup() intoarce zero in caz de reusita. In caz contrar, ea returneaza unul dintre erorile listate in continuare. De retinut ca mecanismul normal prin care aplicatia apeleaza WSAGetLastError() pentru a determina codul de roare nu poate fi folosit, deoarece DLL-ul Windows Sockets se poate sa nu fi stabilit domeniul de date al clientului in care informatia referitoare la "ultima eroare" este memorata.

Coduri de eroare

• WSASYSNOTREADY - Precizeaza ca subsitemul de retea subteran nu este pregatit pentru comunicare cu reteaua.
• WSAVERNOTSUPPORTED - Suportul pentru versiunea Windows Sockets ceruta nu este suportata de aceasta implementare a Windows Sockets.
• WSAEINPROGRESS - O operatie cu blocare a Windows Sockets 1.1 este in desfasurare.
• WSAEPROCLIM - Limita numarului de sarcini suportate de implementarea Windows Sockets a fost atinsa.
• WSAEFAULT - pointerul lpWSAData nu este un pointer valid.

© Cornel Mironel Niculae, 2004-2005
13-Nov-2004