Hello,
the manual page and all documentation of
shishi_parse_name() are inaccurate in the
way they fail to contain an at-sign between
principal name and realm name in two cases.
Also the variable referencing is in error.
The following patch suggestion might mend
this, but I have not really executed the
parsers on the change, though.
The API call shishi_parse_name() is notable
on two more accounts:
* The Shishi handle is part of the signature,
but it is never used, so the expected call
shishi_error() is reporting irrelevant text
when called after a failure in shishi_parse_name().
Can an error condition in shishi_parse_name()
be inserted into the handle's context?
* There is an asymmetry in the return values
`*principal' and `*realm', since the former
always is allocated, while the latter need
not be so. Would it be disruptive to return
`*principal' as NULL when the component is
missing? I have good use of the call
shishi_parse_name(&h, "@EX.ORG", &principal, &realm)
which displays asymmetry in relation to
shishi_parse_name(&h, "me/admin", &principal, &realm)
since `realm = "EX.ORG"' and `principal = ""' in the first
case, and `principal' must be deallocated afterwards.
In contrast, the second case has `realm = NULL'.
Best regards,
Mats E A
diff --git a/lib/principal.c b/lib/principal.c
index d9d8e0c..80e6934 100644
--- a/lib/principal.c
+++ b/lib/principal.c
@@ -97,16 +97,16 @@ shishi_principal_default_set (Shishi * handle, const char *principal)
/**
* shishi_parse_name:
* @handle: Shishi library handle created by shishi_init().
- * @name: input principal name string, e.g. imap/[email protected].
+ * @name: input principal name string, e.g. imap/mail.gnu.org@@GNU.ORG.
* @principal: newly allocated output string with principal name.
* @realm: newly allocated output string with realm name.
*
- * Split principal name (e.g., "[email protected]") into two
- * newly allocated strings, the principal ("simon"), and the realm
- * ("JOSEFSSON.ORG"). If there is no realm part in NAME, REALM is set
+ * Split principal name (e.g., "simon@@JOSEFSSON.ORG") into two
+ * newly allocated strings, the @principal ("simon"), and the @realm
+ * ("JOSEFSSON.ORG"). If there is no realm part in @name, @realm is set
* to NULL.
*
- * Return value: Returns SHISHI_INVALID_PRINCIPAL_NAME if NAME is NULL
+ * Return value: Returns SHISHI_INVALID_PRINCIPAL_NAME if @name is NULL
* or ends with the escape character "\", and SHISHI_OK if
* successful.
**/
_______________________________________________
Help-shishi mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/help-shishi
