Benoemde pijptypen, lees- en wachtmodi

De pijpserver geeft de pijptypemodus, de leesmodus en de wachtmodus op in de parameter dwPipeMode van de functie CreateNamedPipe. Pijpclients kunnen deze pijpmodi voor hun pijpgrepen opgeven met behulp van de functie CreateFile.

Typemodus

De typemodus van een pijp bepaalt hoe gegevens naar een benoemde pijp worden geschreven. Gegevens kunnen via een benoemde pijp worden verzonden als een stroom van bytes of als een stroom berichten. De pijpserver geeft het pijptype op bij het aanroepen van CreateNamedPipe om een exemplaar van een benoemde pijp te maken. De typemodi moeten hetzelfde zijn voor alle exemplaren van een pijp.

Als u een byte-type pipe wilt maken, geeft u PIPE_TYPE_BYTE op of gebruikt u de standaardwaarde. De gegevens worden naar de pijp geschreven als een stroom van bytes en het systeem maakt geen onderscheid tussen de bytes die in verschillende schrijfbewerkingen zijn geschreven.

Als u een berichttypepijp wilt maken, geeft u PIPE_TYPE_MESSAGE op. Het systeem behandelt de bytes die in elke schrijfbewerking zijn geschreven naar de pipe als een berichteenheid. Het systeem voert altijd schrijfbewerkingen uit op message-type pipes alsof de schrijfmodus is ingeschakeld.

Leesmodus

De leesmodus van een pijp bepaalt hoe gegevens uit een benoemde pijp worden gelezen. De pijpserver geeft de initiële leesmodus voor een pijpgreep aan bij het aanroepen van CreateNamedPipe. Gegevens kunnen worden gelezen in de byte-leesmodus of de berichtleesmodus. Een greep naar een byte-type pipe kan alleen in de byte-leesmodus zijn. Een greep naar een berichttypepijp kan zich in de byte-lezen- of berichtleesmodus bevinden. Voor een berichttypepijp kan de leesmodus verschillen voor server- en clientingangen naar hetzelfde pijpexemplaren.

Als u de pijpgreep in de byte-leesmodus wilt maken, geeft u PIPE_READMODE_BYTE op of gebruikt u de standaardwaarde. Gegevens worden uit de pijp gelezen als een stroom van bytes. Een leesbewerking is voltooid wanneer alle beschikbare bytes in de pijp worden gelezen of wanneer het opgegeven aantal bytes wordt gelezen.

Geef PIPE_READMODE_MESSAGE op om de pijpgreep in de berichtenleesmodus te maken. Gegevens worden uit de pijp gelezen als een stroom berichten. Een leesbewerking is alleen voltooid wanneer het hele bericht wordt gelezen. Als het opgegeven aantal bytes dat moet worden gelezen kleiner is dan de grootte van het volgende bericht, leest de functie zoveel mogelijk van het bericht voordat er nul wordt geretourneerd (de functie GetLastError retourneert ERROR_MORE_DATA). De rest van het bericht kan worden gelezen met behulp van een andere leesbewerking.

Voor een pijpclient bevindt een pijpgreep die wordt geretourneerd door CreateFile- zich in eerste instantie altijd in de byte-leesmodus bevindt. Zowel pijpclients als pijpservers kunnen de SetNamedPipeHandleState functie gebruiken om de leesmodus van een pijpgreep te wijzigen. De pijpgreep moet de FILE_WRITE_ATTRIBUTES toegang hebben.

Wachtmodus

De wachtmodus van een pijpgreep bepaalt hoe de ReadFile-, WriteFile-en ConnectNamedPipe-functies langdurige bewerkingen verwerken. In de blokkeringswachtmodus wachten de functies voor onbepaalde tijd op een proces aan het andere uiteinde van de pijp om een bewerking te voltooien. In de niet-blokkeringswachtmodus worden de functies onmiddellijk geretourneerd in situaties waarvoor anders een onbepaalde wachttijd is vereist.

Een ReadFile bewerking wordt beïnvloed door de wachtmodus van een pijpgreep wanneer de pijp leeg is. Met een blokkeringswachtgreep wordt de bewerking niet voltooid totdat gegevens beschikbaar zijn van een thread die naar het andere uiteinde van de pijp wordt geschreven. Met behulp van een niet-blokkeringswachtgreep retourneert de functie onmiddellijk nul en retourneert de functie GetLastError ERROR_NO_DATA.

Een WriteFile--bewerking wordt beïnvloed door de wachtmodus van een pijpgreep wanneer er onvoldoende ruimte in de buffer van de pijp is. Met een blokkeringswachtgreep kan de schrijfbewerking pas slagen als er voldoende ruimte in de buffer is gemaakt door een thread te lezen vanaf het andere uiteinde van de pijp. Met een niet-blokkeringswachtgreep retourneert de schrijfbewerking onmiddellijk een niet-nulwaarde, zonder bytes (voor een bericht-type pipe) te schrijven of na het schrijven van zoveel bytes als de buffer (voor een byte-type pipe).

Een ConnectNamedPipe--bewerking wordt beïnvloed door de wachtmodus van een pijpgreep wanneer er geen client is verbonden of wacht om verbinding te maken met het pijpexemplaren. Met een blokkeringswachtgreep slaagt de verbindingsbewerking pas nadat een pijpclient verbinding maakt met het pijpexemplaren door de CreateFile- of CallNamedPipe--functie aan te roepen. Met een niet-blokkeringswachtgreep retourneert de verbindingsbewerking onmiddellijk nul en retourneert de functie GetLastError ERROR_PIPE_LISTENING.

Standaard worden alle benoemde pijpgrepen die worden geretourneerd door de CreateNamedPipe- of functie CreateFile gemaakt met de blokkeringswachtmodus ingeschakeld. Als u de pijp wilt maken in de modus niet-blokkeringswachttijden, geeft de pijpserver PIPE_NOWAIT op bij het aanroepen van CreateNamedPipe-.

Zowel pijpclients als pijpservers kunnen de wachtmodus van een pijpgreep wijzigen door PIPE_WAIT of PIPE_NOWAIT op te geven in een aanroep naar de functie SetNamedPipeHandleState.

Notitie

De niet-blokkeringswachtmodus wordt ondersteund voor compatibiliteit met Microsoft LAN Manager versie 2.0. Deze modus mag niet worden gebruikt om overlappende invoer en uitvoer (I/O) met benoemde pijpen te bereiken. Overlappende I/O moet in plaats daarvan worden gebruikt, omdat hiermee tijdrovende bewerkingen op de achtergrond kunnen worden uitgevoerd nadat de functie is geretourneerd. Zie synchrone en overlappende invoer- en uitvoer-voor meer informatie over overlappende I/O.