D 2022-10-17T23:29:30.043
L API\sReview\sfor\s1.0
N text/x-markdown
P a4d68acc2a03fdc005871f1ff443053f069743feec127ceaa42ebcafe3c6fdd0
U js
W 12759
# API Review for 1.0

For the 1.0 release, all APIs should be reviewed, as starting with 1.0, they are supposed to be stable. All documented methods, functions, classes, types and structs that are part of the installed headers are considered part of the API.

Right now, we have fhe following installed headers:

* ✅ `ObjFW/macros.h`
* ✅ `ObjFW/objfw-defs.h`
* ✅ `ObjFW/ObjFW.h`
* ✅ `ObjFW/OFAcceptFailedException.h`
* ✅ `ObjFW/OFAllocFailedException.h`
* ✅ `ObjFW/OFAlreadyConnectedException.h`
* ✅ `ObjFW/OFApplication.h`
* ✅ `ObjFW/OFArchiveEntry.h`
* ✅ `ObjFW/OFArray.h`
* ✅ `ObjFW/OFAtomic.h`
* ✅ `ObjFW/OFBindFailedException.h`
* ✅ `ObjFW/OFBlock.h`
* ✅ `ObjFW/OFChangeCurrentDirectoryFailedException.h`
* ✅ `ObjFW/OFCharacterSet.h`
* ✅ `ObjFW/OFChecksumMismatchException.h`
* ✅ `ObjFW/OFCollection.h`
* ✅ `ObjFW/OFColor.h`
* ✅ `ObjFW/OFConditionBroadcastFailedException.h`
* ✅ `ObjFW/OFCondition.h`
* ✅ `ObjFW/OFConditionSignalFailedException.h`
* ✅ `ObjFW/OFConditionStillWaitingException.h`
* ✅ `ObjFW/OFConditionWaitFailedException.h`
* ✅ `ObjFW/OFConnectionFailedException.h`
* ✅ `ObjFW/OFConstantString.h`
* ✅ `ObjFW/OFCopyItemFailedException.h`
* ✅ `ObjFW/OFCountedSet.h`
* ✅ `ObjFW/OFCreateDirectoryFailedException.h`
* ✅ `ObjFW/OFCreateSymbolicLinkFailedException.h`
* ✅ `ObjFW/OFCreateWindowsRegistryKeyFailedException.h`
* ✅ `ObjFW/OFCryptographicHash.h`
* ✅ `ObjFW/OFData+CryptographicHashing.h`
* ✅ `ObjFW/OFDatagramSocket.h`
* ✅ `ObjFW/OFData.h`
* ✅ `ObjFW/OFData+MessagePackParsing.h`
* ✅ `ObjFW/OFDate.h`
* ✅ `ObjFW/OFDeleteWindowsRegistryKeyFailedException.h`
* ✅ `ObjFW/OFDeleteWindowsRegistryValueFailedException.h`
* ✅ `ObjFW/OFDictionary.h`
* ✅ `ObjFW/OFDNSQueryFailedException.h`
* ✅ `ObjFW/OFDNSQuery.h`
* ✅ `ObjFW/OFDNSResolver.h`
* ✅ `ObjFW/OFDNSResourceRecord.h`
* ✅ `ObjFW/OFDNSResponse.h`
* ✅ `ObjFW/OFEnumerationMutationException.h`
* ✅ `ObjFW/OFEnumerator.h`
* ✅ `ObjFW/OFException.h`
* ✅ `ObjFW/OFFile.h`
* ✅ `ObjFW/OFFileManager.h`
* ✅ `ObjFW/OFGetCurrentDirectoryFailedException.h`
* ✅ `ObjFW/OFGetItemAttributesFailedException.h`
* ✅ `ObjFW/OFGetOptionFailedException.h`
* ✅ `ObjFW/OFGetWindowsRegistryValueFailedException.h`
* ✅ `ObjFW/OFGZIPStream.h`
* ✅ `ObjFW/OFHashAlreadyCalculatedException.h`
* ✅ `ObjFW/OFHashNotCalculatedException.h`
* ✅ `ObjFW/OFHMAC.h`
* ✅ `ObjFW/OFHTTPClient.h`
* ✅ `ObjFW/OFHTTPCookie.h`
* ✅ `ObjFW/OFHTTPCookieManager.h`
* ✅ `ObjFW/OFHTTPRequestFailedException.h`
* ✅ `ObjFW/OFHTTPRequest.h`
* ✅ `ObjFW/OFHTTPResponse.h`
* ✅ `ObjFW/OFHTTPServer.h`
* ✅ `ObjFW/OFInflate64Stream.h`
* ✅ `ObjFW/OFInflateStream.h`
* ✅ `ObjFW/OFINICategory.h`
* ✅ `ObjFW/OFINIFile.h`
* ✅ `ObjFW/OFInitializationFailedException.h`
* ✅ `ObjFW/OFInvalidArgumentException.h`
* ✅ `ObjFW/OFInvalidEncodingException.h`
* ✅ `ObjFW/OFInvalidFormatException.h`
* ✅ `ObjFW/OFInvalidJSONException.h`
* ✅ `ObjFW/OFInvalidServerResponseException.h`
* ✅ `ObjFW/OFInvocation.h`
* ✅ `ObjFW/OFIPXSocket.h`
* ✅ `ObjFW/OFJSONRepresentation.h`
* ✅ `ObjFW/OFKernelEventObserver.h`
* ✅ `ObjFW/OFKeyValueCoding.h`
* ✅ `ObjFW/OFLHAArchiveEntry.h`
* ✅ `ObjFW/OFLHAArchive.h`
* ✅ `ObjFW/OFLinkItemFailedException.h`
* ✅ `ObjFW/OFListenFailedException.h`
* ✅ `ObjFW/OFList.h`
* ✅ `ObjFW/OFLoadPluginFailedException.h`
* ✅ `ObjFW/OFLocale.h`
* ✅ `ObjFW/OFLockFailedException.h`
* ✅ `ObjFW/OFLocking.h`
* ✅ `ObjFW/OFMalformedXMLException.h`
* ✅ `ObjFW/OFMapTable.h`
* ✅ `ObjFW/OFMD5Hash.h`
* ✅ `ObjFW/OFMemoryStream.h`
* ✅ `ObjFW/OFMessagePackExtension.h`
* ✅ `ObjFW/OFMessagePackRepresentation.h`
* ✅ `ObjFW/OFMethodSignature.h`
* ✅ `ObjFW/OFMoveItemFailedException.h`
* ✅ `ObjFW/OFMutableArchiveEntry.h`
* ✅ `ObjFW/OFMutableArray.h`
* ✅ `ObjFW/OFMutableData.h`
* ✅ `ObjFW/OFMutableDictionary.h`
* ✅ `ObjFW/OFMutableLHAArchiveEntry.h`
* ✅ `ObjFW/OFMutablePair.h`
* ✅ `ObjFW/OFMutableSet.h`
* ✅ `ObjFW/OFMutableString.h`
* ✅ `ObjFW/OFMutableTarArchiveEntry.h`
* ✅ `ObjFW/OFMutableTriple.h`
* ✅ `ObjFW/OFMutableURI.h`
* ✅ `ObjFW/OFMutableZIPArchiveEntry.h`
* ✅ `ObjFW/OFMutex.h`
* ✅ `ObjFW/OFNotificationCenter.h`
* ✅ `ObjFW/OFNotification.h`
* ✅ `ObjFW/OFNotImplementedException.h`
* ✅ `ObjFW/OFNotOpenException.h`
* ✅ `ObjFW/OFNull.h`
* ✅ `ObjFW/OFNumber.h`
* ✅ `ObjFW/OFObject.h`
* ✅ `ObjFW/OFObject+KeyValueCoding.h`
* ✅ `ObjFW/OFObject+Serialization.h`
* ✅ `ObjFW/OFObserveKernelEventsFailedException.h`
* ✅ `ObjFW/OFOnce.h`
* ✅ `ObjFW/OFOpenItemFailedException.h`
* ✅ `ObjFW/OFOpenWindowsRegistryKeyFailedException.h`
* ✅ `ObjFW/OFOptionsParser.h`
* ✅ `ObjFW/OFOutOfMemoryException.h`
* ✅ `ObjFW/OFOutOfRangeException.h`
* ✅ `ObjFW/OFPair.h`
* ✅ `ObjFW/OFPBKDF2.h`
* ✅ `ObjFW/OFPlainCondition.h`
* ✅ `ObjFW/OFPlainMutex.h`
* ✅ `ObjFW/OFPlainThread.h`
* ✅ `ObjFW/OFPlugin.h`
* ✅ `ObjFW/OFReadFailedException.h`
* ✅ `ObjFW/OFReadOrWriteFailedException.h`
* ✅ `ObjFW/OFRecursiveMutex.h`
* ✅ `ObjFW/OFRemoveItemFailedException.h`
* ✅ `ObjFW/OFResolveHostFailedException.h`
* ✅ `ObjFW/OFRIPEMD160Hash.h`
* ✅ `ObjFW/OFRunLoop.h`
* ✅ `ObjFW/OFScrypt.h`
* ✅ `ObjFW/OFSecureData.h`
* ✅ `ObjFW/OFSeekableStream.h`
* ✅ `ObjFW/OFSeekFailedException.h`
* ✅ `ObjFW/OFSequencedPacketSocket.h`
* ✅ `ObjFW/OFSerialization.h`
* ✅ `ObjFW/OFSet.h`
* ✅ `ObjFW/OFSetItemAttributesFailedException.h`
* ✅ `ObjFW/OFSetOptionFailedException.h`
* ✅ `ObjFW/OFSetWindowsRegistryValueFailedException.h`
* ✅ `ObjFW/OFSettings.h`
* ✅ `ObjFW/OFSHA1Hash.h`
* ✅ `ObjFW/OFSHA224Hash.h`
* ✅ `ObjFW/OFSHA224Or256Hash.h`
* ✅ `ObjFW/OFSHA256Hash.h`
* ✅ `ObjFW/OFSHA384Hash.h`
* ✅ `ObjFW/OFSHA384Or512Hash.h`
* ✅ `ObjFW/OFSHA512Hash.h`
* ✅ `ObjFW/OFSocket.h`
* ✅ `ObjFW/OFSortedList.h`
* ✅ `ObjFW/OFSPXSocket.h`
* ✅ `ObjFW/OFSPXStreamSocket.h`
* ✅ `ObjFW/OFStdIOStream.h`
* ✅ `ObjFW/OFStillLockedException.h`
* ✅ `ObjFW/OFStream.h`
* ✅ `ObjFW/OFStreamSocket.h`
* ✅ `ObjFW/OFString+CryptographicHashing.h`
* ✅ `ObjFW/OFString.h`
* ✅ `ObjFW/OFString+JSONParsing.h`
* ✅ `ObjFW/OFString+PathAdditions.h`
* ✅ `ObjFW/OFString+PercentIEncoding.h`
* ✅ `ObjFW/OFString+PropertyListParsing.h`
* ✅ `ObjFW/OFString+Serialization.h`
* ✅ `ObjFW/OFString+XMLEscaping.h`
* ✅ `ObjFW/OFString+XMLUnescaping.h`
* ✅ `ObjFW/OFSubprocess.h`
* ✅ `ObjFW/OFSystemInfo.h`
* ✅ `ObjFW/OFTarArchiveEntry.h`
* ✅ `ObjFW/OFTarArchive.h`
* ✅ `ObjFW/OFTCPSocket.h`
* ✅ `ObjFW/OFThread.h`
* ✅ `ObjFW/OFThreadJoinFailedException.h`
* ✅ `ObjFW/OFThreadStartFailedException.h`
* ✅ `ObjFW/OFThreadStillRunningException.h`
* ✅ `ObjFW/OFTimer.h`
* ✅ `ObjFW/OFTLSHandshakeFailedException.h`
* ✅ `ObjFW/OFTLSKey.h`
* ✅ `ObjFW/OFTLSStream.h`
* ✅ `ObjFW/OFTriple.h`
* ✅ `ObjFW/OFTruncatedDataException.h`
* ✅ `ObjFW/OFUDPSocket.h`
* ✅ `ObjFW/OFUnboundNamespaceException.h`
* ✅ `ObjFW/OFUnboundPrefixException.h`
* ✅ `ObjFW/OFUndefinedKeyException.h`
* ✅ `ObjFW/OFUNIXDatagramSocket.h`
* ✅ `ObjFW/OFUNIXStreamSocket.h`
* ✅ `ObjFW/OFUnknownXMLEntityException.h`
* ✅ `ObjFW/OFUnlockFailedException.h`
* ✅ `ObjFW/OFUnsupportedProtocolException.h`
* ✅ `ObjFW/OFUnsupportedVersionException.h`
* ✅ `ObjFW/OFURI.h`
* ✅ `ObjFW/OFURIHandler.h`
* ✅ `ObjFW/OFUUID.h`
* ✅ `ObjFW/OFValue.h`
* ✅ `ObjFW/OFWindowsRegistryKey.h`
* ✅ `ObjFW/OFWriteFailedException.h`
* ✅ `ObjFW/OFXMLAttribute.h`
* ✅ `ObjFW/OFXMLCDATA.h`
* ✅ `ObjFW/OFXMLCharacters.h`
* ✅ `ObjFW/OFXMLComment.h`
* ✅ `ObjFW/OFXMLElementBuilder.h`
* ✅ `ObjFW/OFXMLElement.h`
* ✅ `ObjFW/OFXMLElement+Serialization.h`
* ✅ `ObjFW/OFXMLNode.h`
* ✅ `ObjFW/OFXMLParser.h`
* ✅ `ObjFW/OFXMLProcessingInstruction.h`
* ✅ `ObjFW/OFZIPArchiveEntry.h`
* ✅ `ObjFW/OFZIPArchive.h`
* ✅ `ObjFW/platform/GCC4.7/OFAtomic.h`
* ✅ `ObjFW/platform/GCC4/OFAtomic.h`
* ✅ `ObjFW/platform.h`
* ✅ `ObjFW/platform/macOS/OFAtomic.h`
* ✅ `ObjFW/platform/PowerPC/OFAtomic.h`
* ✅ `ObjFW/platform/x86/OFAtomic.h`
* ✅ `ObjFWRT/ObjFWRT.h`
* ✅ `ObjFWTLS/ObjFWTLS.h`

Some things still need to be checked on a global level:

* ✅ Classes that already reserve ivars need to be considered to be changed to restricted subclassing
* ✅ All classes either restrict subclassing or reserve ivars
* ❌ All exception throws need to be audited (they're part of the API, too!)
  * ✅ OFASPrintF.m
  * ✅ OFAdjacentArray.m
  * ✅ OFApplication.m
  * ✅ OFArray.m
  * ✅ OFBitSetCharacterSet.m
  * ✅ OFBlock.m
  * ✅ OFBytesValue.m
  * ✅ OFColor.m
  * ✅ OFCondition.m
  * ✅ OFConstantString.m
  * ✅ OFCountedMapTableSet.m
  * ✅ OFDNSResolver.m
  * ✅ OFDNSResolverSettings.m
  * ✅ OFDNSResourceRecord.m
  * ✅ OFData+MessagePackParsing.m
  * ✅ OFData.m
  * ✅ OFDatagramSocket.m
  * ✅ OFDate.m
  * ✅ OFDictionary.m
  * ✅ OFEmbeddedURIHandler.m
  * ✅ OFEpollKernelEventObserver.m
  * ✅ OFFile.m
  * ✅ OFFileManager.m
  * ✅ OFFileURIHandler.m
  * ✅ OFGZIPStream.m
  * ✅ OFHMAC.m
  * ✅ OFHTTPClient.m
  * ✅ OFHTTPCookie.m
  * ✅ OFHTTPRequest.m
  * ✅ OFHTTPResponse.m
  * ✅ OFHTTPServer.m
  * ✅ OFHostAddressResolver.m
  * ✅ OFHuffmanTree.h
  * ✅ OFINICategory.m
  * ✅ OFINIFile.m
  * ✅ OFIPXSocket.m
  * ✅ OFInflateStream.m
  * ✅ OFKernelEventObserver.m
  * ✅ OFKqueueKernelEventObserver.m
  * ✅ OFLHAArchive.m
  * ✅ OFLHAArchiveEntry.m
  * ✅ OFLHADecompressingStream.m
  * ✅ OFList.m
  * ✅ OFLocale.m
  * ✅ OFMD5Hash.m
  * ✅ OFMapTable.m
  * ✅ OFMapTableDictionary.m
  * ✅ OFMapTableSet.m
  * ✅ OFMemoryStream.m
  * ✅ OFMessagePackExtension.m
  * ✅ OFMethodSignature.m
  * ✅ OFMutableAdjacentArray.m
  * ✅ OFMutableArray.m
  * ✅ OFMutableData.m
  * ✅ OFMutableMapTableDictionary.m
  * ✅ OFMutableString.m
  * ✅ OFMutableURI.m
  * ✅ OFMutableUTF8String.m
  * ✅ OFMutableZIPArchiveEntry.m
  * ✅ OFMutex.m
  * ✅ OFNonretainedObjectValue.m
  * ✅ OFNotificationCenter.m
  * ✅ OFNull.m
  * ✅ OFNumber.m
  * ✅ OFObject+KeyValueCoding.m
  * ✅ OFObject.m
  * ✅ OFOptionsParser.m
  * ✅ OFPBKDF2.m
  * ✅ OFPlugin.m
  * ✅ OFPointValue.m
  * ✅ OFPointerValue.m
  * ✅ OFPollKernelEventObserver.m
  * ✅ OFRIPEMD160Hash.m
  * ✅ OFRangeCharacterSet.m
  * ✅ OFRangeValue.m
  * ✅ OFRectValue.m
  * ✅ OFRecursiveMutex.m
  * ✅ OFSHA1Hash.m
  * ✅ OFSHA224Or256Hash.m
  * ✅ OFSHA384Or512Hash.m
  * ✅ OFSPXSocket.m
  * ✅ OFSPXStreamSocket.m
  * ✅ OFScrypt.m
  * ✅ OFSecureData.m
  * ✅ OFSelectKernelEventObserver.m
  * ✅ OFSequencedPacketSocket.m
  * ✅ OFSizeValue.m
  * ✅ OFSocket.m
  * ✅ OFStdIOStream.m
  * ✅ OFStream.m
  * ✅ OFStreamSocket.m
  * ❌ OFString+JSONParsing.m
  * ❌ OFString+PercentEncoding.m
  * ❌ OFString+PropertyListParsing.m
  * ❌ OFString+Serialization.m
  * ❌ OFString+XMLUnescaping.m
  * ❌ OFString.m
  * ✅ OFSubarray.m
  * ✅ OFTCPSocket.m
  * ✅ OFTLSStream.m
  * ❌ OFTarArchive.m
  * ❌ OFTarArchiveEntry.m
  * ❌ OFThread.m
  * ✅ OFTimer.m
  * ❌ OFUDPSocket.m
  * ❌ OFUNIXDatagramSocket.m
  * ❌ OFUNIXStreamSocket.m
  * ✅ OFURI.m
  * ✅ OFURIHandler.m
  * ❌ OFUTF8String.m
  * ✅ OFUUID.m
  * ❌ OFWindowsRegistryKey.m
  * ✅ OFXMLAttribute.m
  * ✅ OFXMLCDATA.m
  * ✅ OFXMLCharacters.m
  * ✅ OFXMLComment.m
  * ❌ OFXMLElement+Serialization.m
  * ❌ OFXMLElement.m
  * ❌ OFXMLElementBuilder.m
  * ❌ OFXMLParser.m
  * ✅ OFXMLProcessingInstruction.m
  * ❌ OFZIPArchive.m
  * ❌ OFZIPArchiveEntry.m
  * ✅ bridge/NSNumber+OFObject.m
  * ✅ bridge/NSOFArray.m
  * ✅ bridge/NSOFDictionary.m
  * ✅ bridge/NSOFSet.m
  * ✅ bridge/OFException+Swift.m
  * ✅ bridge/OFNSArray.m
  * ✅ bridge/OFNSDictionary.m
  * ✅ bridge/OFNSEnumerator.m
  * ✅ bridge/OFNSSet.m
  * ✅ bridge/OFNumber+NSObject.m
  * ✅ bridge/OFString+NSObject.m
  * ✅ exceptions/OFException.m
  * ✅ libbases.m
  * ❌ platform/POSIX/OFString+PathAdditions.m
  * ❌ platform/POSIX/OFSubprocess.m
  * ❌ platform/Windows/OFString+PathAdditions.m
  * ❌ platform/Windows/OFSubprocess.m
  * ✅ platform/Windows/OFWin32ConsoleStdIOStream.m
  * ❌ platform/libfat/OFString+PathAdditions.m
  * ❌ tls/OFGnuTLSTLSStream.m
  * ❌ tls/OFOpenSSLTLSStream.m
  * ❌ tls/OFSecureTransportTLSStream.m
Z 269c0fc309c1352d340a7fa3fdffbd0e