Index: src/OFXMLElement.h ================================================================== --- src/OFXMLElement.h +++ src/OFXMLElement.h @@ -119,19 +119,27 @@ /** * @brief Parses the string and returns an OFXMLElement for it. * * @param string The string to parse * @return A new autoreleased OFXMLElement with the contents of the string + * @throw OFMalformedXMLException The XML was malformed + * @throw OFUnboundPrefixException A prefix was used that was not bound to any + * namespace + * @throw OFInvalidEncodingException The XML is not in the encoding it specified */ + (instancetype)elementWithXMLString: (OFString *)string; /** * @brief Parses the specified stream and returns an OFXMLElement for it. * * @param stream The stream to parse * @return A new autoreleased OFXMLElement with the contents of the specified * stream + * @throw OFMalformedXMLException The XML was malformed + * @throw OFUnboundPrefixException A prefix was used that was not bound to any + * namespace + * @throw OFInvalidEncodingException The XML is not in the encoding it specified */ + (instancetype)elementWithStream: (OFStream *)stream; - (instancetype)init OF_UNAVAILABLE; @@ -186,19 +194,27 @@ * @brief Parses the string and initializes an already allocated OFXMLElement * with it. * * @param string The string to parse * @return An initialized OFXMLElement with the contents of the string + * @throw OFMalformedXMLException The XML was malformed + * @throw OFUnboundPrefixException A prefix was used that was not bound to any + * namespace + * @throw OFInvalidEncodingException The XML is not in the encoding it specified */ - (instancetype)initWithXMLString: (OFString *)string; /** * @brief Parses the specified stream and initializes an already allocated * OFXMLElement with it. * * @param stream The stream to parse * @return An initialized OFXMLElement with the contents of the specified stream + * @throw OFMalformedXMLException The XML was malformed + * @throw OFUnboundPrefixException A prefix was used that was not bound to any + * namespace + * @throw OFInvalidEncodingException The XML is not in the encoding it specified */ - (instancetype)initWithStream: (OFStream *)stream; /** * @brief Sets a prefix for a namespace. @@ -393,10 +409,13 @@ * with the specified indentation per level. * * @param indentation The indentation per level * @return An OFString representing the OFXMLNode as an XML string with * indentation + * @throw OFUnboundNamespaceException The node uses a namespace that was not + * bound to a prefix in a context where it + * needs a prefix */ - (OFString *)XMLStringWithIndentation: (unsigned int)indentation; /** * @brief Returns an OFString representing the OFXMLElement as an XML string @@ -404,13 +423,16 @@ * * @param defaultNS The default namespace * @param indentation The indentation per level * @return An OFString representing the OFXMLNode as an XML string with * indentation + * @throw OFUnboundNamespaceException The node uses a namespace that was not + * bound to a prefix in a context where it + * needs a prefix */ - (OFString *)XMLStringWithDefaultNamespace: (OFString *)defaultNS indentation: (unsigned int)indentation; @end OF_ASSUME_NONNULL_END #import "OFXMLElement+Serialization.h" Index: src/OFXMLNode.h ================================================================== --- src/OFXMLNode.h +++ src/OFXMLNode.h @@ -38,30 +38,43 @@ */ @property (nonatomic, copy) OFString *stringValue; /** * @brief The contents of the receiver as a `long long` value. + * + * @throw OFInvalidFormatException The node cannot be parsed as a `long long` */ @property (readonly, nonatomic) long long longLongValue; /** * @brief The contents of the receiver as an `unsigned long long` value. + * + * @throw OFInvalidFormatException The node cannot be parsed as an + * `unsigned long long` */ @property (readonly, nonatomic) unsigned long long unsignedLongLongValue; /** * @brief The contents of the receiver as a float value. + * + * @throw OFInvalidFormatException The node cannot be parsed as a `float` */ @property (readonly, nonatomic) float floatValue; /** * @brief The contents of the receiver as a double value. + * + * @throw OFInvalidFormatException The node cannot be parsed as a `double` */ @property (readonly, nonatomic) double doubleValue; /** * @brief A string representing the node as an XML string. + * + * @throw OFUnboundNamespaceException The node uses a namespace that was not + * bound to a prefix in a context where it + * needs a prefix */ @property (readonly, nonatomic) OFString *XMLString; - (instancetype)init OF_UNAVAILABLE; - (instancetype)initWithSerialization: (OFXMLElement *)element OF_UNAVAILABLE; Index: src/OFXMLParser.h ================================================================== --- src/OFXMLParser.h +++ src/OFXMLParser.h @@ -185,24 +185,36 @@ /** * @brief Parses the specified buffer with the specified size. * * @param buffer The buffer to parse * @param length The length of the buffer + * @throw OFMalformedXMLException The XML was malformed + * @throw OFUnboundPrefixException A prefix was used that was not bound to any + * namespace + * @throw OFInvalidEncodingException The XML is not in the encoding it specified */ - (void)parseBuffer: (const char *)buffer length: (size_t)length; /** * @brief Parses the specified string. * * @param string The string to parse + * @throw OFMalformedXMLException The XML was malformed + * @throw OFUnboundPrefixException A prefix was used that was not bound to any + * namespace + * @throw OFInvalidEncodingException The XML is not in the encoding it specified */ - (void)parseString: (OFString *)string; /** * @brief Parses the specified stream. * * @param stream The stream to parse + * @throw OFMalformedXMLException The XML was malformed + * @throw OFUnboundPrefixException A prefix was used that was not bound to any + * namespace + * @throw OFInvalidEncodingException The XML is not in the encoding it specified */ - (void)parseStream: (OFStream *)stream; @end OF_ASSUME_NONNULL_END Index: src/OFZIPArchive.h ================================================================== --- src/OFZIPArchive.h +++ src/OFZIPArchive.h @@ -76,10 +76,11 @@ * For read and append mode, this needs to be an OFSeekableStream. * @param mode The mode for the ZIP file. Valid modes are "r" for reading, * "w" for creating a new file and "a" for appending to an existing * archive. * @return A new, autoreleased OFZIPArchive + * @throw OFInvalidFormatException The format is not that of a valid ZIP archive */ + (instancetype)archiveWithStream: (OFStream *)stream mode: (OFString *)mode; /** * @brief Creates a new OFZIPArchive object with the specified file. @@ -87,10 +88,11 @@ * @param URI The URI to the ZIP file * @param mode The mode for the ZIP file. Valid modes are "r" for reading, * "w" for creating a new file and "a" for appending to an existing * archive. * @return A new, autoreleased OFZIPArchive + * @throw OFInvalidFormatException The format is not that of a valid ZIP archive */ + (instancetype)archiveWithURI: (OFURI *)URI mode: (OFString *)mode; /** * @brief Creates a URI for accessing a the specified file within the specified @@ -113,10 +115,11 @@ * For read and append mode, this needs to be an OFSeekableStream. * @param mode The mode for the ZIP file. Valid modes are "r" for reading, * "w" for creating a new file and "a" for appending to an existing * archive. * @return An initialized OFZIPArchive + * @throw OFInvalidFormatException The format is not that of a valid ZIP archive */ - (instancetype)initWithStream: (OFStream *)stream mode: (OFString *)mode OF_DESIGNATED_INITIALIZER; /** @@ -126,10 +129,11 @@ * @param URI The URI to the ZIP file * @param mode The mode for the ZIP file. Valid modes are "r" for reading, * "w" for creating a new file and "a" for appending to an existing * archive. * @return An initialized OFZIPArchive + * @throw OFInvalidFormatException The format is not that of a valid ZIP archive */ - (instancetype)initWithURI: (OFURI *)URI mode: (OFString *)mode; /** * @brief Returns a stream for reading the specified file from the archive. @@ -145,10 +149,18 @@ * invalidated stream will throw an @ref OFReadFailedException or * @ref OFWriteFailedException! * * @param path The path to the file inside the archive * @return A stream for reading the specified file form the archive + * @throw OFNotOpenException The archive is not open + * @throw OFInvalidArgumentException The archive is not in read mode + * @throw OFOpenItemFailedException Opening the specified file within the + * archive failed + * @throw OFInvalidFormatException The local header and the header in the + * central directory do not match enough + * @throw OFUnsupportedVersionException The file uses a version of the ZIP + * format that is not supported */ - (OFStream *)streamForReadingFile: (OFString *)path; /** * @brief Returns a stream for writing the specified entry to the archive. @@ -171,15 +183,25 @@ * * The compressed size. * * The uncompressed size. * * The CRC32. * * Bit 3 and 11 of the general purpose bit flag. * @return A stream for writing the specified entry to the archive + * @throw OFNotOpenException The archive is not open + * @throw OFInvalidArgumentException The archive is not in write mode + * @throw OFOpenItemFailedException Opening the specified file within the + * archive failed. If @ref errNo is `EEXIST`, + * because there is already a file with the + * same name in the archive. + * @throw OFNotImplementedException The desired compression method is not + * implemented */ - (OFStream *)streamForWritingEntry: (OFZIPArchiveEntry *)entry; /** * @brief Closes the OFZIPArchive. + * + * @throw OFNotOpenException The archive is not open */ - (void)close; @end #ifdef __cplusplus