ObjFW  Update of "API Review for 1.0"

Overview

Artifact ID: 94cccb4c19249606e3679aef294a3a0ad3d6e405c6a8cc4ce4eed032d82479db
Page Name:API Review for 1.0
Date: 2022-08-30 00:50:37
Original User: js
Mimetype:text/x-markdown
Parent: ae048ce2f9d783e3d78cf2b04b79227186411486ebe971c38dda307de9d77650 (diff)
Next 0967dc02877679da642a65a33ffaf8f1f5098e7859ae164b32c703f5a3c05683
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/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/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/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/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