Mit dem Aufruf Extract_Client_Context erhält ein Programm den Client-spezifischen Kontext, den openUTM als letztes gesendet hat.
Der mit Set_Client_Context() an openUTM übergebene Kontext wird bis zum Ende der Conversation gesichert, falls er nicht durch einen neuen Kontext überschrieben wird. Wird vom Client ein Wiederanlauf angefordert, so wird der Kontext zusammen mit der letzten Dialog-Nachricht an den Client zurück übertragen, den openUTM aktuell für diese Conversation gespeichert hat.
Der Client-Kontext wird von openUTM nur gesichert, wenn eine UTM-Benutzerkennung mit Restartfunktionalität angemeldet ist, da nur in diesem Fall ein Vorgangs-Wiederanlauf möglich ist.
Der Aufruf Extract_Client_Context ist im Zustand "Send" und "Receive" und im Zustand "Reset" unmittelbar nach einem Receive-/Receive_Mapped_Data-Aufruf erlaubt.
Extract_Client_Context ist nicht Bestandteil der CPI-C Spezifikation, sondern eine zusätzliche Funktion des UPIC-Trägersystems.
CMECC (conversation_ID, buffer, requested_length, data_received, received_length, return_code)
Parameter
--> conversation_ID | Identifikation der bereits initialisierten Conversation (wird vom Initialize-Aufruf geliefert). |
--> buffer | Puffer, in dem die Daten empfangen werden. |
--> requested_length | Maximale Länge der Daten, die empfangen werden können. |
<-- data_received | Gibt an, ob das Programm den Client-Kontext vollständig empfangen hat. Falls das Ergebnis (return_code) nicht den Wert CM_OK hat, ist der Wert von data_received undefiniert. data_received kann folgende Werte annehmen: CM_COMPLETE_DATA_RECEIVED Der Client-Kontext wurde vollständig empfangen. CM_INCOMPLETE_DATA_RECEIVED Der Client-Kontext ist nicht vollständig vom Programm empfangen worden. CM_NO_DATA_RECEIVED Es wurden keine Daten empfangen. |
<-- received_length | Länge der empfangenen Daten. Ist der Wert von received_length = 0, so liegt kein Client-Kontext vor. Der Wert von received_length ist undefiniert, falls das Ergebnis (return_code) nicht den Wert CM_OK hat. |
<-- return_code | Ergebnis des Funktionsaufrufs. |
Ergebnis ( return_code )
CM_OK
Aufruf OK
CM_PROGRAM_PARAMETER_CHECK
Der Wert in conversation_ID ist ungültig oder der Wert für requested_length ist größer als 32767 oder kleiner 1.
Der Wert der conversation_ID ist ungültig, weil die Funktion nach Ende der Conversation mehr als einmal aufgerufen wurde oder weil noch keine Conversation existierte (nach dem Enable_UTM_UPIC-Aufruf ist noch kein Initialize_Conversation Aufruf erfolgt).
CM_PRODUCT_SPECIFIC_ERROR
Die UPIC-Instanz konnte nicht gefunden werden.
CM_PROGRAM_STATE_CHECK
Die Conversation ist nicht im Zustand "Reset", "Send" oder "Receive".
Hinweis
Falls eine Teilnachricht mit Receive-/Receive_Mapped_Data-Aufruf(en) empfangen wurde (data_received hat den Wert CM_COMPLETE_DATA_RECEIVED), so werden die Parameter client_context und client_context_length bei einem nachfolgenden Receive-/ Receive_Mapped_Data-Aufruf zurückgesetzt.
Der Wert der conversation_ID bleibt für diesen Funktionsaufruf nach dem Ende einer Conversation so lange gültig, bis ein Initialize_Conversation-Aufruf oder ein Extract_Client_Context-Aufruf erfolgt ist.
Der interne Puffer besitzt eine beschränkte Grösse von derzeit 8 Byte.
openUTM sendet derzeit immer einen Client Context der Länge 8 Byte zurück. D.h., wenn von UPIC ein gültiger Client-Kontext empfangen worden ist, so hat received_length die Länge 8.
Falls an openUTM ein Client-Kontext mit einer Länge < 8 Byte gesendet worden ist, dann wird der Client-Kontext von openUTM mit binär null auf die Länge 8 aufgefüllt.Ist der Wert für requested_length kleiner als die Länge des intern gespeicherten client_context, so wird der vom Anwendungsprogramm zur Verfügung gestellte Puffer vollständig gefüllt und data_received auf CM_INCOMPLETE_DATA_RECEIVED gesetzt. Folgt unmittelbar ein weiterer CMECC-Aufruf mit einem genügend großem Wert für requested_length (d.h. >= 8), so wird der Puffer mit einem solchen Aufruf komplett gelesen.
Verhalten im Fehlerfall
CM_PROGRAM_STATE_CHECK
Programm ändern.
CM_PROGRAM_PARAMETER_CHECK
Programm ändern.
CM_PRODUCT_SPECIFIC_ERROR
Das Betriebssystem kann nicht genügend Speicherplatz für interne Puffer bereitstellen. Überprüfen Sie Ihr Programm auf zu hohe Speicherplatzanforderung und starten Sie ggf. Ihr System neu.
CM_ENTRY Extract_Client_Context (
unsigned char CM_PTR conversation_ID,
unsigned char CM_PTR buffer,
CM_INT32 CM_PTR requested_length,
CM_DATA_RECEIVED_TYPE CM_PTR data_received,
CM_INT32 CM_PTR received_length,
CM_RETURN_CODE CM_PTR return_code )