Quelques indices pour payCreator
Yann GAUTERON
yann at gauteron.ch
Thu Apr 26 22:11:08 CEST 2001
Hello,
Voici en attache un fichier contenant un debut d'ebauche pour la librairie
payCreator de creation de paiements electroniques.
Vous remarquerez que la conception est tres fortement inspiree de la COO
(conception orientee objet) au niveau des structures et
methodes. (Naturellement, pas d'heritages, de surcharge et tout le
toutim afin de pouvoir le coder en C et d'etre reutilisable dans divers
projets, comme Compta).
Ces interfaces decrivent:
* le numero de compte postal
* le numero de reference pour BVR
* l'adresse
* le BVR
manquent:
* Le bulletin de versement "simple" (rose ou vert). Y-a-t-il un nom
"scientifique" pour ces types de paiements (BVR pour les bleus).
* L'ordre de paiement electronique (ensemble de paiements BVR et
bulletins roses avec compte a debiter + date de retrait).
* Compte a debiter (postal et banquaire)
* Un concept pour la conversion vers DTA / OPAE...
J'attends donc impatiemment vos remarques, questions et suggestions
concernant les "classes" deja proposees.
Par ailleurs, des questions sont posees dans le document. Toutes les
reponses sont les bienvenues.
Yann
-------------- next part --------------
payCreator (the Core library)
=============================
panb: Postal Account Number structure and functions
====----------------------------------------------
panb_t: Structure (hidden to the library user)
panb_p: Pointer to the pan_t structure
panb_p panb_new(char *str) - Create a new "instance" of a panb_t "class".
*str (the referenced value not the pointer itself) will be stored
in the structure as the postal account number.
Return NULL if an error occured.
int panb_free(panb_p panb) - Free the ressources allocated to the
structure.
The return value will indicate what kind of error occured.
panb_p panb_copy(panb_p panb) - Create a copy of the panb "instance" and
return the pointer to the new "instance".
int panb_setNumber(panb_p panb, char *str) - Set a new value for the
postal account number in panb.
*str (the referenced value not the pointer itself) will be stored
in pnb as the postal account number.
Return an error value if parameter is not correct (validation -
see below - is not checked) or if malloc failed).
The return value will indicate what kind of error occured.
*char panb_getNumber(panb_p panb) - Return a "usual format" copy of the
stored postal account number.
The format is "XX-xxxxxX-X" (9 positions account number) or "XXXXX"
(5 positions account number).
Return NULL if an error occured or no value is stored in panb.
*char panb_getRawNumber(panb_p panb) - Return a "computer format" copy of
the postal account number in panb.
The format is "XXXXXXXXX" (9 positions account number) or "XXXXX"
(5 positions account number). This format is used for any
processing or storing requirements.
Return NULL if an error occured or no value is stored in panb.
int panb_isValid(panb_p panb) - Check if the stored value is correct or
not. The 2 first digits in 9 positions account number are checked
to be valid (I still miss the valid range: 01 = BVR CHF,
03 = BVR EUR, the remaining - 00, 02, 04-99 - are they all valids ?)
and key checksum is computed and compared with the account number
key digit).
Return TRUE if it is valid, FALSE else.
int panb_isKeyValid(panb_p panb) - Check if the key of the stored value
is valid or not.
Return TRUE if it is valid, FALSE else.
int panb_isPrefixValid(panb_p panb) - Check if the "prefix" (exact name has
to be found for the 2 first digits) is valid or not (see above).
Return TRUE if it is valid, FALSE else.
char panb_computeKey(panb_p panb) - Compute the key of the postal account
number stored in panb. The postal account number is not modified
with this value!
Return '0'...'9' for the key value, 0 if an error occured.
char panb_setKey(panb_p panb) - Compute and set the key of the postal account
number stored in panb.
Return '0'...'9' for the key value, 0 if an error occured.
// other still not defined functions (account type information (BVR in CHF,
// BVR in EUR, other type).
Question about panb_new:
Should panb_new accept an initialization value or not ?
Advantage of doing so: It's possible to create an "instance" of the "class"
and to set up an initial value in one step.
Disadvantage: Contrary to panb_setNumber, the return value can not inform
the calling function if the parameter is correct or not.
Example:
panb_p panb;
...
if(!(panb = panb_new("Once upon a time..."))) {
// ERROR but we are not warned
// except if the "main" malloc
// failed and if the return value
// egals NULL.
if(!panb_setNumber("Once upon a time, again...")) {
// ERROR, the parameter is invalid
// and the return value warn us.
// We can also catch with other
// values malloc failures.
}
...
}
Question about panb_getXXXNumber:
Do these functions return a pointer to a field inside the structure or do
they return a pointer to a copy of this field ?
First case is better if we would like to use the return value only once as
a parameter of a function. Else we need to store the value in a temporary
pointer and we will need to free the memory right after the function
call.
Second case is better if we want to access this value after the fields in
the structure have been changed (but it's still possible to do a strcpy for
getting the same result).
Case 1)
Advantage:
panb_p panb;
char *result;
...
panb = panb_new("20-36934-3"); // Now, panb contains "20-36934-3"
result = panb_getNumber(panb); // result points to a copy of
// "20-36934-3"
...
panb_setNumber(panb, "01-123456-1");
// Now, panb contains "01-123456-1"
printf("'result' value: %c\n",
result); // result still points to a copy of
// "20-36934-3"
Disadvantage:
panb_p panb;
char *tmp;
...
panb = panb_new("20-36934-3");
printf("Postal account number: %c\n",
panb_getNumber(panb)); // ERROR: Memory allocated for the
// copy will not be freed.
printf("Postal account number: %c\n",
tmp = panb_getNumber(panb));
free(tmp); // Right way, but need two step for
// a single thing.
Case 2)
Advantage:
panb_p panb;
...
printf("Postal account number: %c\n",
panb_getNumber(panb)); // Correct. A pointer to a string in
// the structure is given.
// No memory should be freed.
Disadvantage:
panb_p panb;
char *result1;
char *result2;
...
panb = panb_new("20-36934-3"); // panb contains "20-36934-3"
result1 = panb_getResult(panb); // result points to the structure
// field filled with "20-36934-3"
result2 = strcpy(panb_getResult(panb));
// Copy of the field inside the
// structure.
...
panb_setNumber(panb, "01-123456-1");
// panb contains now "01-123456-1"
printf("'result1' value: %c\n",
result1); // result1 still points to the field
// in the structure ("01-123456-1")
printf("'result2' value: %c\n",
result2); // result2 still points to the copy
// of the previous value of the field
// in the structure ("20-36934-3")
// Conclusion: To get the same result of the 1st case, we need to
// strcpy the return value of the function.
My question is:
* Which case (1st or 2nd) is better ? The goal is to reuse the existing
habits in order to avoid programming errors from the library
user.
refnb: Reference number used in BVR
=====------------------------------
refnb_t: Structure (hidden to the library user)
refnb_p: Pointer to the bvr_t structure
refnb_p refnb_new(char *str) - Create a new "instance" of a refnb_t "class".
*str (the referenced value not the pointer itself) will be stored
in the structure as the reference number.
int refnb_free(refnb_p refnb) - Free the ressources allocated to the
structure.
The return value will indicate what kind of error occured.
refnb_p refnb_copy(refnb_p refnb) - Create a copy of the refnb "instance" and
return the pointer to the new "instance".
int refnb_setNumber(refnb_p refnb, char *str) - Set a new value for the
reference number in refnb.
*str (the referenced value not the pointer itself) will be stored
in refnb as the reference number.
Return an error value. 0 if no error occured.
*char refnb_getNumber(refnb_p refnb) - Return a "usual format" copy of the
stored reference number.
The digits are grouped 5 by 5. No leading zero is inserted.
Return NULL if an error occured or no value is stored in refnb.
*char refnb_getRawNumber(refnb_p refnb) - Return a "computer format" copy of
the referenc number in refnb.
The digits are viewed in one group (no space inserted each 5 digits).
No leading zero is inserted.
Return NULL if an error occured or no value is stored in refnb.
int refnb_isKeyValid(refnb_p refnb) - Check if the key of the stored value
is valid or not.
Return TRUE if it is valid, FALSE else.
char refnb_computeKey(refnb_p refnb) - Compute the key of the reference
number stored in refnb. The reference number is not modified
with this value!
Return '0'...'9' for the key value, 0 if an error occured.
char refnb_setKey(refnb_p refnb) - Compute and set the key of the reference
number stored in refnb.
Return '0'...'9' for the key value, 0 if an error occured.
address: Postal address
=======----------------
address_t: Structure (hidden to the library user)
address_p: Pointer to the address_t structure
address_p address_new(char *str) - Create a new "instance" of a address_t
"class".
*str (the referenced value not the pointer itself) will be stored
in the structure as the address.
The first line (after removing the leading empty lines) will be saved
as the name (last and first or company)
The last line (after removing the queuing empty lines) will be saved
as the city (zip code and city).
The lines between will be saved as the address (p.o. box and/or
street).
Return NULL if an error occured.
int address_free(address_p refnb) - Free the ressources allocated to the
structure.
The return value will indicate what kind of error occured.
address_p address_copy(address_p panb) - Create a copy of the address
"instance" and return the pointer to the new "instance".
int address_setAddress(address_p address, char *str) - Set the full address
*str (the referenced value not the pointer itself) will be stored
in the structure address.
The same remark than above apply for the different fields to be
stored.
Return an error value if parameter is not correct or if malloc
failed.
The return value will indicate what kind of error occured.
int address_setName(address_p address, char *name) - Set the name in the
structure address. The name can be stored on many lines (using '\n').
Return an error value if parameter is not correct or if malloc
failed.
int address_setStreet(address_p address, char *address) - Set the street in
structure address.
Return an error value if parameter is not correct or if malloc
failed.
int address_setCity(address_p address, char *city) - Set the city in the
structure address. The city can be stored on many lines (using '\n').
Return an error value if parameter is not correct or if malloc
failed.
char *address_getName(address_p address) - Return the name in the address.
Return the name if the function succeeds, NULL else.
char *address_getStreet(address_p address) - Return the street in the address.
Return the street if the function succeeds, NULL else.
char *address_getCity(address_p address) - Return the city in the address.
Return the city if the function succeeds, NULL else.
Same question as "panb" for the "address_getXXXXX(...)" functions.
bvr: BVR payement slip
===-------------------
bvr_t: Structure (hidden to the library user) will contain:
int paydisc; // Payement discriminator (BVR = 1)
panb_p rcptpanb; // Recipient postal account number
refnb_p refnb; // Reference number
char *amount; // Amount of the payement
char currency[4]; // Currency of the payment (CHF, EUR, ...)
// (ISO ???)
address_p rcptaddress; // Recipient address
bvr_p: Pointer to the bvr_t structure
bvr_p bvr_new() - Create a new "instance" of the "class" bvr.
Return NULL if an error occured.
int bvr_setRcptPan(bvr_p bvr, panb_p rcptpanb) - Copy the recipient given as
in the structure.
int bvr_setRefNb(bvr_p bvr, refnb_p refnb) - Copy the reference number as
in the structure.
int bvr_setRcptAddress(bvr_p bvr, address_p rcptaddress) - Copy the address
in the structure.
int bvr_setCurrency(bvr_p bvr, char *currency) - Copy the currency in the
structure.
int bvr_setAmount(bvr_p bvr, char *amount) - Copy the amount in the
structure.
panb_p bvr_getRcptPan(bvr_p bvr) - Return the recipient postal account
number.
refnb_p bvr_getRefNb(bvr_p bvr) - Return the reference number.
char *bvr_getAmount(bvr_p bvr) - Return the amount.
char *bvr_getCurrency(bvr_p bvr) - Return the currency.
Same question for "bvr_getXXXX()" functions.
More information about the compta
mailing list