TsgcWebTransportStream › Methoden › Close

Close Methode

Meldet den Stream von seiner Sitzung ab und löst OnClose einmalig aus. Nur ein lokales Signal: Der Peer wird nicht benachrichtigt.

Syntax

procedure Close;

Hinweise

Close markiert den Stream als geschlossen, meldet ihn durch den Aufruf von Session.RemoveStream von seiner Sitzung ab und löst dann OnClose aus. Die Reihenfolge ist wichtig: Die Sitzung spiegelt bereits den neuen StreamCount wider, während Ihr OnClose-Handler läuft, und FindStreamById gibt den Stream nicht mehr zurück, sodass nach dem Schließen keine eingehenden Daten mehr an ihn geleitet werden können.

Es lohnt sich, ausdrücklich zu sagen, was sie nicht tut, denn der Name verspricht mehr:

• es wird kein QUIC FIN oder RESET_STREAM gesendet, dem Peer wird also nicht mitgeteilt, dass der Stream beendet wurde;
• der zugrunde liegende QUIC-Stream wird nicht geschlossen, er bleibt offen;
• er gibt den Stream nicht frei. Die Sitzung bleibt dessen Eigentümerin und gibt ihn frei, wenn die Sitzung freigegeben wird;
• es blockiert spätere Schreibvorgänge nicht. WriteData nach Close erreicht weiterhin den Writer.

Es ist gegen wiederholte Aufrufe abgesichert. Das Closed-Flag wird zuerst geprüft, sodass ein zweimaliger Aufruf von Close das Ereignis OnClose genau einmal auslöst, und TsgcWebTransportSession.Close ist auf dieselbe Weise abgesichert. Das gilt unter Delphi, C++Builder und .NET gleichermaßen, und auf jedem Stack meldet Close den Stream von seiner Sitzung ab, bevor das Ereignis ausgelöst wird.

Verwenden Sie es als Ihren eigenen End-of-Stream-Marker und hängen Sie das Aufräumen an OnClose. Da nichts gesendet wird, muss ein Peer, der wissen muss, dass ein Stream beendet ist, über Ihr Protokoll informiert werden: Senden Sie eine Sentinel-Nachricht oder vereinbaren Sie, dass ein bestimmter Austausch den Stream beendet. Bei der Gegenstelle kommt nichts an, wenn Sie dies aufrufen.

Der Stream bleibt nach der Rückkehr von Close vollständig gültig und bleibt am Leben, bis seine Sitzung zerstört wird, sodass jede Referenz, die Sie darauf behalten haben, sicher gelesen werden kann. Es ist nicht nötig, danach Session.RemoveStream aufzurufen, Close hat dies bereits erledigt. Geschlossene Streams werden erst mit der Sitzung freigegeben, wenn Sie sie also über eine langlebige Sitzung hinweg fortlaufend öffnen, bevorzugen Sie weniger und langlebigere Streams.

Unter .NET stellt die verwaltete Klasse zusätzlich eine öffentliche Eigenschaft IsClosed bereit, die von Close gesetzt wird und mit der Sie prüfen können, ob ein Stream geschlossen wurde. Delphi und C++Builder halten dasselbe Flag privat und stellen kein Äquivalent bereit.

Beispiel

procedure TfrmClient.FinishExchange;
begin
  if not Assigned(FStream) then
    Exit;

  // The peer is NOT told, so if it needs to know, our protocol must say so
  FStream.WriteData('BYE');

  FStream.Close;   // raises OnClose once; safe to call again
  FStream := nil;  // owned by the session, so do not free it
end;

procedure TfrmClient.OnStreamClose(Sender: TObject);
var
  oStream: TsgcWebTransportStream;
begin
  // The stream is still valid here, so its state can be read
  oStream := TsgcWebTransportStream(Sender);
  memoLog.Lines.Add('stream ' + IntToStr(oStream.StreamId) + ' closed');
end;

Zurück zu Methoden