ObjFW  Update of "API Review for 1.0"

Overview

Artifact ID: ac9d299da8e01e4fe4a570a9b8ef3c1c6ba820fd535f972b1252c5da525c0b0e
Page Name:API Review for 1.0
Date: 2022-06-12 08:53:20
Original User: js
Mimetype:text/x-markdown
Parent: 421016cbba46899c0b82169d1351bd91d45de9a07359889995a28fad3ea371b4 (diff)
Next 3b3dbdd64f4e0f4897c73a7fbc8b9762bcb4a3e93dd45b316f22bd97a4e54af2
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/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/OFCryptographicHash.h
  • ObjFW/OFData+CryptographicHashing.h
  • ObjFW/OFDatagramSocket.h
  • ObjFW/OFData.h
  • ObjFW/OFData+MessagePackParsing.h
  • ObjFW/OFDate.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/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/OFMessagePackExtension.h
  • ObjFW/OFMessagePackRepresentation.h
  • ObjFW/OFMethodSignature.h
  • ObjFW/OFMoveItemFailedException.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/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/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/OFThreadPool.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/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:

  • ❌ Includes that are not installed on every OS
  • ❌ 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!)
  • ❌ OFSerialization is up for consideration to be removed