ObjFW  Update of "API Review for 1.0"

Overview

Artifact ID: 2be0029af245326df690ea35708842479911485786e915ddf3e7400a790601a9
Page Name:API Review for 1.0
Date: 2022-09-16 21:19:45
Original User: js
Mimetype:text/x-markdown
Parent: 86b6af3df53f622d25caa711759eaa97b9ee8e68a5b432a2f2080be05c45ef4a (diff)
Next e89102815bf224b4ec4f8a1cc8946cedd20d026a8cde0c9579ef6c59711b5e34
Content

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/OFChangeCurrentDirectoryPathFailedException.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/OFGetCurrentDirectoryPathFailedException.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/OFInvalidServerReplyException.h
  • ObjFW/OFInvocation.h
  • ObjFW/OFIPXSocket.h
  • ObjFW/OFJSONRepresentation.h
  • ObjFW/OFKernelEventObserver.h
  • ObjFW/OFKeyValueCoding.h
  • ObjFW/OFLHAArchiveEntry.h
  • ObjFW/OFLHAArchive.h
  • ObjFW/OFLinkFailedException.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/OFMutableURL.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/OFObserveFailedException.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/OFRetrieveItemAttributesFailedException.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+PropertyListParsing.h
  • ObjFW/OFString+Serialization.h
  • ObjFW/OFString+URLEncoding.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/OFURL.h
  • ObjFW/OFURLHandler.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
    • ❌ OFEmbeddedFileURLHandler.m
    • ❌ OFEpollKernelEventObserver.m
    • ❌ OFFile.m
    • ❌ OFFileManager.m
    • ❌ OFFileURLHandler.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
    • ❌ OFMutableURL.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+PropertyListParsing.m
    • ❌ OFString+Serialization.m
    • ❌ OFString+URLEncoding.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
    • ❌ OFURL.m
    • ❌ OFURLHandler.m
    • ❌ OFUTF8String.m
    • ❌ OFUUID.m
    • ❌ OFWin32ConsoleStdIOStream.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/libfat/OFString+PathAdditions.m
    • ❌ tls/OFGnuTLSTLSStream.m
    • ❌ tls/OFOpenSSLTLSStream.m
    • ❌ tls/OFSecureTransportTLSStream.m