Cephei — General

  • Executes a shell command and returns its output.

    Declaration

    Objective-C

    NSString *_Nullable HBOutputForShellCommand(NSString *_Nonnull command)

    Swift

    func HBOutputForShellCommand(_ command: String) -> String?

    Parameters

    command

    The shell command to run. @returns The output of the provided command, or nil if the command returned with a code other than 0.

  • Executes a shell command and returns its output.

    Declaration

    Objective-C

    NSString *_Nullable HBOutputForShellCommandWithReturnCode(
        NSString *_Nonnull command, int *_Nonnull returnCode)

    Swift

    func HBOutputForShellCommandWithReturnCode(_ command: String, _ returnCode: UnsafeMutablePointer<Int32>) -> String?

    Parameters

    command

    The shell command to run.

    returnCode

    A pointer to an integer that will contain the return code of the command. @returns The output of the provided command.

  • The HBPreferences class in Cephei provides an interface for managing user-defined preferences of a tweak, and the default values used when the user has not yet changed a value.

    HBPreferences is very similar to NSUserDefaults, however it is specifically tailored to iOS tweak development, since tweaks may be loaded into a sandboxed process (most obviously, App Store apps, but also system apps like Safari), or one that runs as the root user (for instance, iFile, although these apps are slowly changing their model so they now run as mobile). In both of these cases, using NSUserDefaults will result in reading from preferences inside the sandbox, or inside root’s home directory; both of which are not what is expected.

    Advantages HBPreferences has over NSUserDefaults are:

    • Directly reading the property list from the mobile user’s home directory, to support sandboxed apps and apps running as root.
    • Intuitive method of setting a default preference value.
    • Updating of the app/tweak’s variables when preferences are changed.
    • Keyed subscripting is allowed, which enables simple array syntax.
    • Values in the preferences plist are called preferences, not defaults, to avoid ambiguity - NSUserDefaults uses “defaults” to refer to both preferences themselves and the fallback values if a key doesn’t exist.

    Ensure you read the discussion for -[HBPreferences registerObject:default:forKey:] before using the automatic updating mechanism. -[HBPreferences objectForKey:] does not update as another process updates the preferences on iOS 7 or older; if you need to support older iOS versions, use the registration methods instead.

    Example usage

    HBPreferences *preferences;
    BOOL doThing;
    
    %ctor {
        preferences = [[HBPreferences alloc] initWithIdentifier:@"ws.hbang.common.demo"];
        [preferences registerDefaults:@{
            @"Enabled": @YES,
            @"AnotherSetting": @1.f
        }];
    
        [preferences registerBool:&doThing default:NO forKey:@"DoThing"];
    
        NSLog(@"Am I enabled? %i", [preferences boolForKey:@"Enabled"]);
        NSLog(@"Can I do thing? %i", doThing);
    }
    

    References

    Security

    As of Cephei 1.12, HBPreferences restricts most Apple preferences (identifiers starting with com.apple.…) from being read/written from a sandboxed process. This protects against a malicious app using HBPreferences as a way to gather sensitive information or change system preferences without the user’s knowledge. For instance, an App Store app could phish for the user’s Apple ID login, creating a very real-looking login prompt by pre-filling their email address in the username box, or gain access to the numbers/email addresses of people the user has recently contacted.

    There is currently no way to avoid this restriction while still using HBPreferences. If you need access to Apple preferences, design your code to not need to do this from within the sandbox. This could be done using IPC from an unsandboxed process such as SpringBoard. Avoid sending sensitive information via IPC to sandboxed apps, as they can still get access to data you send through various ways.

    If this is an inconvenience for you and you believe an exception should be made, please file an issue to discuss it.

    See more

    Declaration

    Objective-C

    @interface HBPreferences : NSObject

    Swift

    class HBPreferences : NSObject
  • The HBRespringController class in Cephei provides conveniences for restarting the system app (usually SpringBoard). It also ensures battery usage statistics are not lost when performing the restart.

    See more

    Declaration

    Objective-C

    @interface HBRespringController : NSObject

    Swift

    class HBRespringController : NSObject
  • NSDictionary (HBAdditions) is a class category in Cephei that provides some convenience methods.

    See more

    Declaration

    Objective-C

    @interface NSDictionary (HBAdditions)
  • NSLayoutConstraint (CompactConstraint), a class category from Marco Arment’s CompactConstraint library, is integrated with Cephei. CompactConstraint provides an Auto Layout grammar and methods that are easier to use and understand than UIKit’s built in functions for programmatically adding constraints.

    Refer to its readme to learn how to use it. There are two changes to note: most importantly, the methods have an hb_ prefix, and two methods that are marked as deprecated in the original project have been removed.

    CompactConstraint is licensed under the MIT License.

    See more

    Declaration

    Objective-C

    @interface NSLayoutConstraint (CompactConstraint)
  • NSString (HBAdditions) is a class category in Cephei that provides some convenience methods.

    See more

    Declaration

    Objective-C

    @interface NSString (HBAdditions)
  • UIColor (HBAdditions) is a class category in Cephei that provides some convenience methods.

    See more

    Declaration

    Objective-C

    @interface UIColor (HBAdditions)
  • UIView (CompactConstraint), a class category from Marco Arment’s CompactConstraint library, is integrated with Cephei. CompactConstraint provides an Auto Layout grammar and methods that are easier to use and understand than UIKit’s built in functions for programmatically adding constraints.

    Refer to its readme to learn how to use it. There are two changes to note: most importantly, the methods have an hb_ prefix, and two methods that are marked as deprecated in the original project have been removed.

    CompactConstraint is licensed under the MIT License.

    See more

    Declaration

    Objective-C

    @interface UIView (CompactConstraint)