r3314 - in trunk/libmnetutil: include/libmnetutil source
mikaelsv at minisip.org
mikaelsv at minisip.org
Wed Jun 13 21:07:08 CEST 2007
Author: mikaelsv
Date: 2007-06-13 21:07:08 +0200 (Wed, 13 Jun 2007)
New Revision: 3314
Modified:
trunk/libmnetutil/include/libmnetutil/LdapUrl.h
trunk/libmnetutil/source/LdapUrl.cxx
Log:
* Added some documentation
Modified: trunk/libmnetutil/include/libmnetutil/LdapUrl.h
===================================================================
--- trunk/libmnetutil/include/libmnetutil/LdapUrl.h 2007-06-13 18:19:14 UTC (rev 3313)
+++ trunk/libmnetutil/include/libmnetutil/LdapUrl.h 2007-06-13 19:07:08 UTC (rev 3314)
@@ -24,6 +24,11 @@
#include <string>
#include <vector>
+/**
+ * Represents an LDAP URL Extension.
+ *
+ * Does not have any methods, only data members.
+ */
class LdapUrlExtension {
public:
LdapUrlExtension(std::string type, std::string value, bool critical) : type(type), value(value), critical(critical) {}
@@ -32,15 +37,14 @@
std::string type;
std::string value;
};
+
/**
- * Conforms to the LDAP URL specification (RFC 4516) with the following exceptions:
+ * Represents and parsed LDAP URLs.
+ *
+ * Known problems with respect to LDAP URL specification (RFC 4516):
* - Does not handle case-insensitive URL parts correctly (requires lower-cased reserved words)
- * - b
- * - c
- * - d
+ * - It is not known if the distinguished name and attribute selectors are parsed correctly
*
- * For details about the specification one should read http://tools.ietf.org/html/rfc4516.
- *
* Other fancy notes:
* - There is not setExtension method
*
@@ -51,17 +55,45 @@
LdapUrl(std::string url);
LdapUrl();
- /** Restore URL parts to their default values */
+ /**
+ * Restore URL parts to their default values
+ */
void clear();
+
+ /**
+ * Tests whether or not the currenct LdapUrl instance represents a valid LDAP URL.
+ *
+ * At the moment an LDAP URL is considered invalid only if it doesn't start with "ldap://".
+ */
bool isValid();
- /** Parse URL */
+ /**
+ * Parse URL
+ */
void setUrl(const std::string url);
- /** Get string representation of URL, e.g. the actual URL */
+ /**
+ * Get string representation of URL, e.g. the actual URL.
+ *
+ * This representation may look exactly the same as the original URL as the parser
+ * replaces omitted values with default values. This is not a problem in itself as
+ * the generated URLs are still valid, albeit more explicit than the original ones.
+ *
+ * An example of this:
+ * @code
+LdapUrl url("ldap://ldap.example.net/?");
+cout << url.getString();
+ * @endcode
+ * Output:
+ * @code
+ldap://ldap.example.net:389/??base?(objectClass=*)
+ * @endcode
+ */
std::string getString() const;
- /** Prints all information about the URL */
+ /**
+ * Prints all information about the URL. Probably only useful when debugging.
+ */
void printDebug();
/* Getters and setters */
@@ -75,6 +107,19 @@
void setAttributes(std::vector<std::string>);
std::vector<LdapUrlExtension> getExtensions() const;
+
+ /**
+ * Returns whether or not the LDAP URL has a critical extension.
+ *
+ * The LDAP URL RFC describes why this is important:
+ *
+ * "If an LDAP URL extension is implemented (that is, if the
+ * implementation understands it and is able to use it), the
+ * implementation MUST make use of it. If an extension is not
+ * implemented and is marked critical, the implementation MUST NOT
+ * process the URL. If an extension is not implemented and is not
+ * marked critical, the implementation MUST ignore the extension."
+ */
bool hasCriticalExtension() const;
std::string getFilter() const;
@@ -95,8 +140,10 @@
int32_t scope;
/**
- * Unreserved Characters according to RFC 3986 (section 2.3).
+ * Tests whether or not a character is an "unreserved character".
*
+ * Unreserved Characters according to RFC 3986 (section 2.3):
+ *
* Characters that are allowed in a URI but do not have a reserved
* purpose are called unreserved. These include uppercase and lowercase
* letters, decimal digits, hyphen, period, underscore, and tilde.
@@ -104,21 +151,48 @@
bool isUnreservedChar(char in) const;
/**
- * Reserved Charachters according to RFC 3986 (section 2.2).
+ * Tests whether or not a character is a "reserved character".
*
- * URIs include components and subcomponents that are delimited by
- * characters in the "reserved" set. These characters are called
- * "reserved" because they may (or may not) be defined as delimiters by
+ * Reserved Charachters according to RFC 3986 (section 2.2):
+ *
+ * "URIs include components and subcomponents that are delimited by
+ * characters in the 'reserved' set. These characters are called
+ * 'reserved' because they may (or may not) be defined as delimiters by
* the generic syntax, by each scheme-specific syntax, or by the
- * implementation-specific syntax of a URI's dereferencing algorithm.
+ * implementation-specific syntax of a URI's dereferencing algorithm."
*/
bool isReservedChar(char in) const;
+ /**
+ * Percent-encode a character.
+ *
+ * Converts a space to "%20" and so on. Note that the function converts the input character
+ * regardsless of whether or not a conversion is actually necessary (if an "a" is sent
+ * to the function it will be converted to "%61" even though it is within the US-ACII set).
+ */
std::string encodeChar(const char in) const;
+
+ /**
+ * Decode an percent-encoded character.
+ *
+ * Assumes that the input string is three characters long, that the first
+ * character is the "%" sign and that the last two charachters are hexadecimal digits.
+ */
char decodeChar(const std::string in) const;
+
+ /**
+ * Converts hexadecimal (or decial) digit into the corresponding integer value.
+ */
int32_t charToNum(const char in) const;
+ /**
+ * Parses string and converts all its percent-encoded characters to single characters.
+ */
std::string percentDecode(const std::string & in) const;
+
+ /**
+ * Percent-encodes string according to rules stated in section 2.1 of RFC 4516.
+ */
std::string percentEncode(const std::string & in, bool escapeComma, bool escapeQuestionmark = true) const;
bool validUrl;
Modified: trunk/libmnetutil/source/LdapUrl.cxx
===================================================================
--- trunk/libmnetutil/source/LdapUrl.cxx 2007-06-13 18:19:14 UTC (rev 3313)
+++ trunk/libmnetutil/source/LdapUrl.cxx 2007-06-13 19:07:08 UTC (rev 3314)
@@ -5,12 +5,12 @@
#include <ldap.h>
LdapUrl::LdapUrl(std::string url) {
- clear();
- setUrl(url);
+ clear(); // Reset URL parts to default values
+ setUrl(url); // Parse supplied URL
}
LdapUrl::LdapUrl() {
- clear();
+ clear(); // Reset URL parts to default values
}
void LdapUrl::clear() {
@@ -23,16 +23,22 @@
attributes = std::vector<std::string>();
extensions = std::vector<LdapUrlExtension>();
}
+
std::string LdapUrl::getString() const {
+ // Start off with the schema and host name
std::string url("ldap://");
url += host;
if (port > 0) {
url += ':';
url += itoa(port);
}
+
+ // Append distinguished name (base DN)
url += '/';
url += percentEncode(dn, false, true);
+
+ // Append attributes
url += '?';
if (attributes.size() > 0) {
for (int i=0; i<attributes.size(); i++) {
@@ -41,12 +47,18 @@
url += percentEncode(attributes.at(i), false, true);
}
}
+
+ // Append scope
url += '?';
url += (scope == LDAP_SCOPE_BASE ? "base" : (scope == LDAP_SCOPE_SUBTREE ? "sub" : "one"));
+
+ // Append filter
url += '?';
if (filter.length() > 0) {
url += filter;
}
+
+ // Append extensions
if (extensions.size() > 0) {
url += '?';
for (int i=0; i<extensions.size(); i++) {
@@ -81,12 +93,7 @@
}
return false;
}
-/*
- ldapurl = scheme COLON SLASH SLASH [host [COLON port]]
- [SLASH dn [QUESTION [attributes]
- [QUESTION [scope] [QUESTION [filter]
- [QUESTION extensions]]]]]
-*/
+
void LdapUrl::setUrl(const std::string url) {
std::string::size_type lastPos = 0, pos = 0, posTemp = 0;
@@ -99,13 +106,11 @@
pos = url.find('/', lastPos);
- // lastPos = <first char after schema specifier>, pos = <first "/" after schema specifier>
-
if (pos == std::string::npos) {
// No slash after schema specifier. This means that the URL at most specified a host and a port.
pos = url.length();
- //lastPos = pos;
}
+
if (pos != lastPos) {
// Host or port found
posTemp = url.find(':', lastPos);
@@ -121,7 +126,6 @@
if (lastPos < url.length()) {
std::string restOfUrl = url.substr(lastPos);
- //std::cerr << restOfUrl;
std::vector<std::string> parts = split(restOfUrl, false, '?', true);
More information about the Minisip-devel
mailing list