ObjFW  Update of "API Review for 1.0"

Overview

Artifact ID: 0c5a4a4644b3ffcbb2c9269342fd3fd47fd1e23d055d0c70a3d9824e697d564a
Page Name:API Review for 1.0
Date: 2022-10-21 13:08:36
Original User: js
Mimetype:text/x-markdown
Parent: 9e7694de5f30b0300a23589ff186dc01349b0bc2d98ccbdd4217ea85ab33368c (diff)
Next 83bfae77d8c897994821eff5c05a036d8af2b4bbb5ff97dae95276116f5384b6
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/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