API同步函数.docx

API同步函数.docx

《API同步函数.docx》由会员分享，可在线阅读，更多相关《API同步函数.docx（81页珍藏版）》请在冰豆网上搜索。

API同步函数

API同步函数

accept

（1）

bind（3）

closesocket（5）

connect（7）

gethostbyaddr（10）

gethostbyname（11）

getpeername（12）

getservbyname（13）

getsockname（14）

getsockopt（15）

hostent（22）

htonl（23）

htons（23）

IN_ADDR（24）

inet_addr（24）

inet_ntoa（25）

ioctlsocket（26）

listen（27）

ntohl（28）

ntohs（29）

recv（29）

recvfrom（32）

select（34）

send（36）

sendto（38）

servent（41）

setsockopt（41）

shutdown（47）

sockaddr（49）

sockaddr_atm（49）

sockaddr_gen（51）

socket（51）

SOCKET_ADDRESS（53）

accept

Theacceptfunctionpermitsanincomingconnectionattemptonasocket.

SOCKETaccept（SOCKETs,structsockaddr*addr,int*addrlen）;

Parameters

s[in]Descriptoridentifyingasocketthathasbeenplacedinalisteningstatewiththelistenfunction.Theconnectionisactuallymadewiththesocketthatisreturnedbyaccept.

addr[out]Optionalpointertoabufferthatreceivestheaddressoftheconnectingentity,asknowntothecommunicationslayer.TheexactformatoftheaddrparameterisdeterminedbytheaddressfamilythatwasestablishedwhenthesocketfromtheSOCKADDRstructurewascreated.

addrlen[out]Optionalpointertoanintegerthatcontainsthelengthofaddr.

ReturnValuesIfnoerroroccurs,acceptreturnsavalueoftypeSOCKETthatisadescriptorforthenewsocket.Thisreturnedvalueisahandleforthesocketonwhichtheactualconnectionismade.

Otherwise,avalueofINVALID_SOCKETisreturned,andaspecificerrorcodecanberetrievedbycallingWSAGetLastError.

Theintegerreferredtobyaddrleninitiallycontainstheamountofspacepointedtobyaddr.Onreturnitwillcontaintheactuallengthinbytesoftheaddressreturned.

Errorcode

Meaning

WSANOTINITIALISED

AsuccessfulWSAStartupcallmustoccurbeforeusingthisfunction.

WSAENETDOWN

Thenetworksubsystemhasfailed.

WSAEFAULT

Theaddrlenparameteristoosmalloraddrisnotavalidpartoftheuseraddressspace.

WSAEINTR

AblockingWindowsSockets1.1callwascanceledthroughWSACancelBlockingCall.

WSAEINPROGRESS

AblockingWindowsSockets1.1callisinprogress,ortheserviceproviderisstillprocessingacallbackfunction.

WSAEINVAL

Thelistenfunctionwasnotinvokedpriortoaccept.

WSAEMFILE

Thequeueisnonemptyuponentrytoacceptandtherearenodescriptorsavailable.

WSAENOBUFS

Nobufferspaceisavailable.

WSAENOTSOCK

Thedescriptorisnotasocket.

WSAEOPNOTSUPP

Thereferencedsocketisnotatypethatsupportsconnection-orientedservice.

WSAEWOULDBLOCK

Thesocketismarkedasnonblockingandnoconnectionsarepresenttobeaccepted.

Remarks

Theacceptfunctionextractsthefirstconnectiononthequeueofpendingconnectionsonsockets.Itthencreatesandreturnsahandletothenewsocket.Thenewlycreatedsocketisthesocketthatwillhandletheactualconnection;ithasthesamepropertiesassockets,includingtheasynchronouseventsregisteredwiththeWSAAsyncSelectorWSAEventSelectfunctions.

Theacceptfunctioncanblockthecalleruntilaconnectionispresentifnopendingconnectionsarepresentonthequeue,andthesocketismarkedasblocking.Ifthesocketismarkedasnonblockingandnopendingconnectionsarepresentonthequeue,acceptreturnsanerrorasdescribedinthefollowing.Afterthesuccessfulcompletionofacceptreturnsanewsockethandle,theacceptedsocketcannotbeusedtoacceptmoreconnections.Theoriginalsocketremainsopenandlistensfornewconnectionrequests.

Theparameteraddrisaresultparameterthatisfilledinwiththeaddressoftheconnectingentity,asknowntothecommunicationslayer.Theexactformatoftheaddrparameterisdeterminedbytheaddressfamilyinwhichthecommunicationisoccurring.Theaddrlenisavalue-resultparameter;itshouldinitiallycontaintheamountofspacepointedtobyaddr;onreturnitwillcontaintheactuallength（inbytes）oftheaddressreturned.

Theacceptfunctionisusedwithconnection-orientedsockettypessuchasSOCK_STREAM.Ifaddrand/oraddrlenareequaltoNULL,thennoinformationabouttheremoteaddressoftheacceptedsocketisreturned.

NotesforATM

Thefollowingareimportantissuesassociatedwithconnectionsetup,andmustbeconsideredwhenusingAsynchronousTransferMode（ATM）withWindowsSockets2:

TheacceptandWSAAcceptfunctionsdonotnecessarilysettheremoteaddressandaddresslengthparameters.Therefore,whenusingATM,thecallershouldusetheWSAAcceptfunctionandplaceATM_CALLING_PARTY_NUMBER_IEintheProviderSpecificmemberoftheQOSstructure,whichitselfisincludedinthelpSQOSparameterofthecallbackfunctionusedinaccordancewithWSAAccept.

Whenusingtheacceptfunction,realizethatthefunctionmayreturnbeforeconnectionestablishmenthastraversedtheentiredistancebetweensenderandreceiver.ThisisbecausetheacceptfunctionreturnsassoonasitreceivesaCONNECTACKmessage;inATM,aCONNECTACKmessageisreturnedbythenextswitchinthepathassoonasaCONNECTmessageisprocessed（ratherthantheCONNECTACKbeingsentbytheendnodetowhichtheconnectionisultimatelyestablished）.Assuch,applicationsshouldrealizethatifdataissentimmediatelyfollowingreceiptofaCONNECTACKmessage,datalossispossible,sincetheconnectionmaynothavebeenestablishedallthewaybetweensenderandreceiver.

Requirements

Client:

IncludedinWindows XP,Windows 2000Professional,Windows NTWorkstation,Windows Me,Windows 98,andWindows 95.

Server:

IncludedinWindowsServer 2003,Windows 2000Server,andWindows NTServer.

Header:

DeclaredinWinsock2.h.

Library:

UseWs2_32.lib.

SeeAlsoWindowsSocketsAPIReference,WindowsSocketsFunctions,bind,connect,listen,select,sockaddr,socket,WSAAsyncSelect,WSAAccept

bind

Thebindfunctionassociatesalocaladdresswithasocket.

intbind（SOCKETs,conststructsockaddr*name,intnamelen）;

Parameters

s[in]Descriptoridentifyinganunboundsocket.

name[in]AddresstoassigntothesocketfromtheSOCKADDRstructure.

namelen[in]Lengthofthevalueinthenameparameter,inbytes.

ReturnValuesIfnoerroroccurs,bindreturnszero.Otherwise,itreturnsSOCKET_ERROR,andaspecificerrorcodecanberetrievedbycallingWSAGetLastError.

Errorcode

Meaning

WSANOTINITIALISED

AsuccessfulWSAStartupcallmustoccurbeforeusingthisfunction.

WSAENETDOWN

Thenetworksubsystemhasfailed.

WSAEACCES

AttempttoconnectdatagramsockettobroadcastaddressfailedbecausesetsockoptoptionSO_BROADCASTisnotenabled.

WSAEADDRINUSE

Aprocessonthecomputerisalreadyboundtothesamefully-qualifiedaddressandthesockethasnotbeenmarkedtoallowaddressreusewithSO_REUSEADDR.Forexample,theIPaddressandportareboundintheaf_inetcase）.（SeetheSO_REUSEADDRsocketoptionundersetsockopt.）

WSAEADDRNOTAVAIL

Thespecifiedaddressisnotavalidaddressforthiscomputer.

WSAEFAULT

Thenameornamelenparameterisnotavalidpartoftheuseraddressspace,thenamelenparameteristoosmall,thenameparametercontainsanincorrectaddressformatfortheassociatedaddressfamily,orthefirsttwobytesofthememoryblockspecifiedbynamedoesnotmatchtheaddressfamilyassociatedwiththesocketdescriptors.

WSAEINPROGRESS

AblockingWindowsSockets1.1callisinprogress,ortheserviceproviderisstillprocessingacallbackfunction.

WSAEINVAL

Thesocketisalreadyboundtoanaddress.

WSAENOBUFS

Notenoughbuffersavailable,toomanyconnections.

WSAENOTSOCK

Thedescriptorisnotasocket.

Remarks

Thebindfunctionisusedonanunconnectedsocketbeforesubsequentcallstotheconnectorlistenfunctions.Itisusedtobindtoeitherconnection-oriented（stream）orconnectionless（datagram）sockets.Whenasocketiscreatedwithacalltothesocketfunction,itexistsinanamespace（addressfamily）,butithasnonameassignedtoit.Usethebindfunctiontoestablishthelocalassociationofthesocketbyassigningalocalnametoanunnamedsocket.

AnameconsistsofthreepartswhenusingtheInternetaddressfamily:

Theaddressfamily.

Ahostaddress.

Aportnumberthatidentifiestheapplication.

InWindowsSockets2,thenameparameterisnotstrictlyinterpretedasapointertoaSOCKADDRstructure.ItiscastthiswayforWindowsSockets1.1compatibility.Serviceprovidersarefreetoregarditasapointertoablockofmemoryofsizenamelen.Thefirst2bytesinthisblock（correspondingtothesa_familymemberoftheSOCKADDRstructure）mustcontaintheaddressfamilythatwasusedtocreatethesocket.Otherwise,anerrorWSAEFAULToccurs.

Ifanapplicationdoesnotcarewhatlocaladdressisassigned,specifythemanifestconstantvalueADDR_ANYforthesa_datamemberofthenameparameter.Thisallowstheunderlyingserviceprovidertouseanyappropriatenetworkaddress,potentiallysimplifyingapplicationprogramminginthepresenceofmultihomedhosts（thatis,hoststhathavemorethanonenetworkinterfaceandaddress）.

ForTCP/IP,iftheportisspecifiedaszero,theserviceproviderassignsauniqueporttotheapplicationwithavaluebetween1024and5000.Theapplicationcanusegetsocknameaftercallingbindtolearntheaddressandtheportthathasbeenassignedtoit.IftheInternetaddressisequaltoINADDR_ANY,getsocknamecannotnecessarilysupplytheaddressuntilthesocketisconnected,sinceseveraladdressescanbevalidifthehostismultihomed.Bindingtoaspecificportnumberotherthanport0isdiscouragedforclientapplications,sincethereisadangerofconflictingwithanothersocketalreadyusingthatportnumber.

Note  WhenusingbindwiththeSO_EXCLUSIVEADDRorSO_REUSEADDRsocketoption,thesocketoptionmustbesetpriortoexecutingbindtohaveanyaffect.

NotesforIrDAS