CXI-Basis-Programmierreferenz / Version 2 / Tools / INI-Dateien /

UpdateIniFile - Schreiben eines Eintrags (allgemein)

char * cxiUpdateIniFile (const char *fname, const char *sname, const char *vname, const char *value, CxiLong options)

Schreiben eines INI-Eintrags

fname:
Name der INI-Datei

sname:
Name des Abschnitts ohne Klammern

vname:
Name der Variablen

value:
Neuer Wert der Variablen

options:
cxiOptUpdateIniString oder cxiOptUpdateIniLiteral (siehe Text)

return:
0 ok, sonst Fehler

Diese Funktion ändert eine Variable in einer INI-Datei. Zum Löschen einer Variablen ist value=NULL anzugeben.

Um einen ganzen Abschnitt zu löschen, ist vname=NULL zu übergeben.

Anmerkungen:
Die Datei und der Abschnitt werden angelegt, falls sie nicht existieren.
Existiert die Variable bereits, wird sie an gleicher Stelle ersetzt.
Existiert der Abschnitt, aber nicht die Variable, so wird sie am Anfang des Abschnitts eingefügt.
Existiert der Abschnitt nicht, wird er am Anfang der Datei neu erstellt.

Wird für options der Wert cxiOptUpdateIniString angegeben, ist diese Funktion identisch zu WriteIniFileString:
Wird die Variable neu angelegt oder ersetzt, generiert diese Funktion die passenden Anführungszeichen. Dies führt dazu, dass beim Einlesen mittels CxiTree-Konstruktor, SetFromStringOrFile oder ReadIniFileString die Zeichenfolge immer als Zeichenkette mit allen Leer- und Sonderzeichen interpretiert wird.
Enthält der Wert value sowohl einfache (') wie doppelte (") Anführungszeichen, wird ein Fehler gemeldet (cxiErrorWriteIniFileNoQuote).
Beispiele:

  geschriebene Zeichenfolge       gelesener Wert
  -------------------------       ----------------------------------
  "Dies ist ein Test"             "Dies ist ein Test"
  "TRUE"                          "TRUE"          (String)
  "123"                           "123"           (String)
  "a, b,c"                        "a, b,c"        (String)
  "d + e ; f"                     "d + e ; f"

Wird für options der Wert cxiOptUpdateIniLiteral oder 0 angegeben, bestehen folgende Unterschiede:
Wird die Variable neu angelegt oder ersetzt, erfolgt keinerlei Überprüfung des neuen Wertes auf Sonderzeichen etc. Er wird in jedem Fall unverändert in die Textdatei geschrieben. Dies führt dazu, dass beim Einlesen mittels CxiTree-Konstruktor oder SetFromStringOrFile die Zeichenfolge wie bei SetFromStringOrFile beschrieben interpretiert wird.
Anführungszeichen im Parameter value werden nicht gesondert behandelt.
Diese Option bietet sich an, wenn obige Konvertierungen explizit gewünscht sind oder die Datei auch von anderen Programmen ohne CXI gelesen wird (z.B. WIN.INI).
Beispiele:

  geschriebene Zeichenfolge       gelesener Wert
  -------------------------       ----------------------------------
  "Dies ist ein Test"             "DiesisteinTest"
  "TRUE"                          TRUE            (logisch!)
  "123"                           123             (numerisch!)
  "a, b,c"                        "a", "b", "c"   (Liste)
  "d + e ; f"                     "d+e"           (; ist Kommentar!)

Portabilität:
Diese Funktion ist ab Version 2.11 in allen unterstützten Systemen verfügbar.

Siehe auch:
ReadIniFileString - Lesen eines Eintrags (String)
WriteIniFileString - Schreiben eines Eintrags (String)

Beispiel 1:

Eintragen der Variablen "welt" in den Abschnitt [hallo]
in der Datei "otto.ini" im aktuellen Verzeichnis,
der Wert ist "Dies ist ein Test", wobei dieser Wert als CXI-String
erhalten bleiben soll.

  #include "cxib.h"

  CxiError rc = cxiUpdateIniFile
                ("otto.ini", "hallo", "welt", "Dies ist ein Test",
                 cxiOptUpdateIniString);

  if (rc != cxiNoError) { ...Fehlerbehandlung... }

Beispiel 2:

Eintragen der Variablen "welt" in den Abschnitt [hallo]
in der Datei "otto.ini" im aktuellen Verzeichnis,
der Wert ist "Dies ist ein Test", wobei dieser Wert unverändert
eingetragen werden soll.

  #include "cxib.h"

  CxiError rc = cxiUpdateIniFile
                ("otto.ini", "hallo", "welt", "Dies ist ein Test",
                 cxiOptUpdateIniLiteral);

  if (rc != cxiNoError) { ...Fehlerbehandlung... }