Leonnears Dev

I love Twitter clients for mobile devices for some reason.

New song! The Kingdom Full Of Young Hearts.

The new track is here! Enjoy.

If you have been reading about iOS jailbreak development, or you actually do write jailbreak apps and tweaks, you have undoubtedly heard about header dumping. Of course, you need to dump the private framework headers to actually use them, and you may have thought about doing it yourself. Personally, I decided to dump my own iOS 5.0 headers, since most dumps out there are awful and unedited (except for @rpetrich’s iOS 4.0 headers, which are great, but there are some issues with iOS 5.0).

Okay, so you may actually be in my same situation. Or you just want to dump your own headers to learn a bit more about what the process like. You have heard there are two most used tools do dump iOS headers: class-dump and class-dump-z, but you don’t know what the differences are and you are having problems choosing which one to use (you may have no idea of what they are supposed to do!)

I started dumping my own headers lately. It is a time consuming process, and I have played with both tools. Let me tell you a bit about them…

class-dump was made to dump any Mac OS X frameworks. Since iOS is basically based on Max OS X to certain extent, it can dump iOS headers pretty well. class-dump-z was made specifically for iOS framework dumps, but like everything it’s not perfect.

class-dump can dump every Objective-C framework perfectly fine. It cannot even fetch basic information out C frameworks, though. The main gotcha about class-dump is that it will generate things like this:

#import "NSObject.h"

@class NSConditionLock, NSInvocation;

@interface AKDeferredReply : NSObject
{
    NSInvocation *_invocation;
    NSConditionLock *_blockingLock;
}

+ (id)currentReply;
+ (void)initialize;
- (void)becomeCurrentReply;
- (void)resignCurrentReply;
- (id)invocation;
- (void)setReturnValue:(void*)arg1; //TAKE A LOOK HERE. How it names parameters...
- (void)sendReply;
- (id)init;
- (id)initWithInvocation:(id)arg1 andBlockingLock:(id)arg2
- (void)dealloc;

@end

Like you can see, it doesn’t name parameter variables very well. “arg1”, “arg2”, are not really clear names at all. Now, thanks to Objective-C’s semantic nature, we can give more descriptive names to our parameter variables thanks to the parameter naming feature. So, if we have a method called [foo callSomeoneWithBar], we can just name our variable bar. Every now and then we won’t be able to deduce parameter names though: It may be a rare occurence, but if a given parameter is of type ID and it doesn’t have a descriptive parameter name, then we won’t know what a function is supposed to receive.

Another problem I have found with class-dump is that sometimes it doesn’t fetch message return types properly. Many times it can’t even guess what something receives or accepts as parameter, specially if they are C-Structs. I have seen messages that simply return (or accept) “struct” (without actually telling us what the struct is - it literally places the keyword struct) and sometimes it deduces the type as “struct __CGPoint”… Or something crazy like that.

class-dump-z addresses class-dump’s first issue nicely quite nicely. Instead of giving you “arg1, arg2, arg3” and so on for message parameters, it will give you actual names. class-dump-z dumps, considerably frequent, generates headers like this:

#import "XXUnknownSuperclass.h"

@class NSConditionLock, NSInvocation;

@interface  AKDeferredReply: XXUnknownSuperclass // ??? WTF
{
    NSInvocation *_invocation;
    NSConditionLock *_blockingLock;
}

+ (id)currentReply;
+ (void)initialize;
- (void)becomeCurrentReply;
- (void)resignCurrentReply;
- (id)invocation;
- (void)setReturnValue:(void*)value;
- (void)sendReply;
- (id)init;
- (id)initWithInvocation:(id)invocation andBlockingLock:(id)lock; //Nice parameter naming.
- (void)dealloc;

@end

Okay, you can see it generates parameter names just nice and self describing, so if you dump everything using class-dump-z you will have a bunch of self documented headers that will make your open development easier to do. But you may be asking yourself, what the heck is that “XXUnknownSuperclass” thing. This is class-dump-z’s biggest defect. Many times, frequently enough, it won’t be able to infer what classes are being included in files and what class an object is inheriting from. If you use class-dump-z, you should REALLY keep this in mind because fixing your headers and attempting to replace “XXUnknownSuperclass” with the right class is not as easy as a quick guess job. Most of the time, these XXUnknownSuperclass is NSObject, but it can be UIView sometimes, or NSThread, and sometimes even classes you may have never heard about.

Another huge disadvantage from class-dump-z is that there may be multiple XXUnknownSuperclass’es spread throughout the whole framework dump. XXUnknownSuperclass may be an object of it’s own, and if a framework has multiple classes class-dump-z can’t infer, it will stash all those XXUnknownSuperclass files into one huge XXUnknownSuperclass.m file. This file can be huge. Usually, unknown classes are objects that conform to protocols, but they are all stashed into this huge file that doesn’t make distinctions between it’s files, lacks other includes, and is an overall mess that is impossible to understand.

So okay, if class-dump gives you dumps without proper parameter naming, and class-dump-z has a huge XXUnknownSuperclass issue, which tool should you use to dump your headers? The answer is not a nice nor fast one: You have to use both. If you’re serious about dumping your own iOS headers, whether it is for personal use or to share them with people, then the best thing you can do is to dump frameworks with both, and then edit one of the framework dumps to complete it. This can be challenging at first, because both tools sometimes give you different files, and a different quantity of files. Personally, when I dump my headers with both tools, I work on the files generated by class-dump, completing them with the parameter names fetched from class-dump-z. Again, it’s not a fast thing to do, but I think it’s the best way to do it because you can simply copy all the method declarations from class-dump-z dumps and paste them in class-dump dumps. This way you won’t have XXUnknownSuperclass issues and all your method parameters will be nicely named.

After editing a class-dump file, filling it’s missing info with pieces from a class-dump-z file, I have a file like this:

#import "NSObject.h"

@class NSConditionLock, NSInvocation;

@interface AKDeferredReply : NSObject
{
    NSInvocation *_invocation;
    NSConditionLock *_blockingLock;
}

+ (id)currentReply;
+ (void)initialize;
- (void)becomeCurrentReply;
- (void)resignCurrentReply;
- (id)invocation;
- (void)setReturnValue:(void*)value;
- (void)sendReply;
- (id)init;
- (id)initWithInvocation:(id)invocation andBlockingLock:(id)lock;
- (void)dealloc;

@end

So we have a nice file ready to be used by anyone who needs it/wants to use it!

All in all, if you have considered dumping your own headers, then don’t be certain a simple batch run of class-dump or class-dump-z will do the trick. Many people who dumped their headers and made them available for others to obtain didn’t consider any of this issues and it’s hell to work with them. Specially class-dump-z files, which the constant appearance of XXUnknownSuperclass makes them literally unusable. With raw class-dump files, you can at least try to guess the parameter names and be lucky most of the time, but is still no ideal. So if you’re going to dump your own iOS headers, arm yourself with time and patience. Personally, I have been working for a week on mine and plan to make them available to people, but it sure needs patience because editing headers… Well, making mistakes is a very easy thing to do.

New song!

http://macrumo.rs/ABifeN

(via Instapaper)

http://lifehac.kr/z7936a

(via Instapaper)

Taken with instagram

I made this a very long time. I think it’s a good for a first attempt. Lemme know!

In this small tutorial, I’m going to teach you how to write a small notification center widget for iOS using Theos. We’ll be building a simple widget that contains a custom button that, when pushed, it will present a TWTweetComposeViewController modally so you can write tweets from the notification center.

Along the way I will show you how to:

• Add official iOS frameworks for your Theos projects.
• How to load images (because with Theos it isn’t as easy as [UIImage imageNamed:]!)
• How to install other templates for Theos to use.

That’s it. You’ll be building a very simple widget but it should help you getting started with Theos and notification center widgets.

This is not a tutorial for people new to iPhone development, so please make sure you have experience with iOS development before proceeding. There are many websites and books that will teach you iPhone development, so if you don’t know anything about iOS development, spend a few months building (or attempting to build) an app or two first: I’ll wait for you and this tutorial won’t be going anywhere.

Finally, I’ not going to teach you how to install Theos on your computer. Please refer to this page to learn how to install and configure Theos properly for your machine. The good thing about Theos is that you don’t need a Mac to write your widgets, you can use Linux and Windows as well. Once you have everything, we can get started!

1. Getting The Templates

First things first: Theos doesn’t come with the needed template to write Notification Center widgets, so you have to download that first.

Dustin L. Howett (@DHowett), the creator of Theos, is hosting the Notification Center widget and a few other templates on big Github here. Feel free to download all of them, but we only need “notification_center_widget.nic” for this tutorial.

Once you download the template (shouldn’t take long since it is a small file), save it on the YOUR_THEOS_DIRECTORY/templates/iphone/ directory (On Mac OS X, the default location is /opt/theos/templates/iphone/).

Once you have that, you don’t need to do anything else.

2. Creating The Project

Time to create the actual project. Open up the Terminal Window/Windows command prompt and navigate to a directory of your choice. I recommend you you create the project in a folder under your account’s folder to avoid permission issues. Another recommendation is to avoid having folders with spaces in their names. At least to me under Mac OS X, Theos had problems creating and compiling the source when the project path had spaces or other special characters.

Once you navigate to the folder of your choice on your terminal window, type in this command (it will vary according to your OS, but it’s just the directory of the nic.pl file):

/opt/theos/bin/nic.pl

That will show you the list of available templates for Theos to use (the option should 5, so go ahead and press that).

It will ask you for a project name. Something like “iNotitweet” or anything you want will do.

Next it will ask you for a package name, which is the reverse-DNS notation you used on normal iPhone projects before. I named my package “com.leonnears.openDev.inotitweet”.

Author/Maintainer name is self explanatory.

If for some reason you got lost in the wizard, here you have a screenshot of the terminal window once it is complete. It shows all the commands you need to put in order to create your project:

3. Building the Actual Widget.

Okay, time to get started with the juice!

Go to your project’s folder. Theos has created a project folder with the project name (with no caps) in the folder you were in when you executed the commands.

In your folder, you will have the following files and folders:

• BBWeeAppController-Protocol.h: This is the protocol needed by the widget. You won’t need to modify this file 99% of the time.
• control: This is an interesting file. It contains all the metadata about your project such as iOS Firmware requirements, the author, project name, identifier. Additionally, in this file you can define it’s Cydia details, such as the tweak’s description, what folder it should be located in, etc.. In the end you will need to modify this file a bit, at least to change it’s description.
• {YOUR_PROJECT_NAME}Controller.m (In my case, and in your case if you named the project iNotitweet, iNotitweetController.m): This is the main of your whole project. Here you will write absolutely all the code needed for your widget.
• Makefile: Another very important file. In this file you tell your widget which iOS frameworks it needs and so on. You may or may not need to modify this file, depending on your project (in our case, we will modify this file).
• Resources Folder: Here you need to save all the resources for your project, including but not limited to images.
• Theos (shortcut): This is just a shortcut to the Theos directory in your PC.

So let’s start. Open up your favorite code editor, and open iNotitweetController.m. Time to get our hands dirty.

The first thing you will notice is that there is no companion iNotitweetController.h file for the file you have open. This is because for tweak development, it is a lot better to both define and implement classes in the same file. It’s a lot better to compile and deploy them that way.

Look for the implementation of loadPlaceHolderView, and you will find this. Don’t erase or modify this code unless you need to! This code will load the placeHolder view where your widget goes. Unless you want more customization or want to change the widget’s size, you don’t need to modify the coded provided to you here. Of course we can add more code below it, but the rest of the work is done in other methods of the template (such as loadFullView).

Go get some buttons for the project and save them in your project’s Resources Folder. You will need both a retina and a low resolution button. Well since this is not an official project, you can just use one or the other. If you don’t want to look for buttons, I have made this for an imomplete widget I was writing. Feel free to use this buttons for this test project only:

Now it’s time to start writing some code, and keep in mind one important thing. You need to write all your UI objects by hand. You cannot use Interface Builder for your widgets or other Theos template projects. So make sure you know how to build objects with code (if you can’t, you can pick this up along the way since it’s not a hard thing to do).

In the templates, you can code as you would with any other iOS projects. The process of creating is exactly the same. Only deployment is different compared to official iOS development.

Go to the loadFullView method. Here we create the objects to the views created by loadPlaceholderView.

Before proceeding, you will need to add a button, but like I said at the beginning of this tutorial, it’s not as easy as [IImage imageNamed:]. When it comes to tweak development, using imageNamed would look for an image on your device’s Springboard, which won’t work 99% of the time (unless you guess the name of a springboard image!).

At the beginning of your code there is a method called +(void)initialize. The only code here is the creation of an NSBundle that looks like this:

_iQuickCommunicatorWeeAppBundle = [[NSBundle bundleForClass:[self class]] retain];

You will need to use this object to fetch all the resources in your Resources folder. It may look obvious, but the truth is that at first when I started making widgets, I literally spent around 9 hours trying to figure out how to load images, because none of the methods worked. Luckily for me, DHowett came to my rescue and explained to me how things work, and now I’ explaining this to you to save a wasteful afternoon or even whole day!

Now that you know that and have those tweet buttons saved in your Resources folder, we may proceed.

We are going to create the UI first an later we will concern ourselves with the actual functioning of the tweak. So create a single custom UIButton, and, based on the explanation above, set the tweet buttons as the button’s background. Then just add it as a subview of _view:

This is what I did:

——————————————

-(void)loadFullView {
	// Add subviews to _backgroundView (or _view) here.
	UIButton *tweet = [UIButton buttonWithType:UIButtonTypeCustom];
	[tweet setBackgroundImage:[UIImage imageWithContentsOfFile:
					[_iNotitweetWeeAppBundle pathForResource:@"tweet"
					ofType:@"png"]] forState:UIControlStateNormal];
	tweet.frame = CGRectMake(2, 0, 79, 33);
	[tweet addTarget:self action:@selector(composeTweet) forControlEvents:UIControlEventTouchDown];
	[_view addSubview:tweet];
}

——————————————

You may have noticed the selector doesn’t exist. So just scroll all the way up and add it to the class definition at first as -(void)composeTweet. Then go back down to the class implementation and write it’s skeleton like this:

-(void)composeTweet {

}

Finally, we will actually modify our widget’s size to be as tall as the button, so go down to the loadPlaceholderView, and look for this line:

_view = [[UIView alloc] initWithFrame:(CGRect){CGPointZero, {316.f, [self viewHeight]}}];

This line should be the first one in the method. Do the following small change:

_view = [[UIView alloc] initWithFrame:(CGRect){CGPointZero, {316.f, 33.f}}];

The button is 33 points high, so our widget should be just as big.

Time to compile and see what we got! We are not finished yet, but so far it’s a great point to see if what we have looks fine. So in your terminal window type the following commands:

export THEOS_DEVICE_IP=INSERT_YOUR_DEVICES_IP_HERE
make package install

Theos will create a deb and install it over sftp to your device. So make sure your computer where you are developing and your phone are connected to the same network before running those commands. 

Once it compiles, Theos will put it in your device and your device will respiring afterwards. Now you need to enable your widget in the Notification Center settings before you can see it, so go to Settings > Notifications > scroll down till you find iNotitweet (or the name of your project), dig in and enable it.

Once you enable it, if you have been following along, you should see the widget in the notification center like this:

We’re almost finishing. Everything that is left is to actually show the TWTweetComposeViewController view when the button is tapped. And that is easy as pie.

First, you need to include the Twitter framework at the beginning of your code:

#import <Twitter/Twitter.h>

But that alone won’t link your project to the Twitter framework. Now open up the Makefile file and look for this line.

iNotitweet_FRAMEWORKS = UIKit CoreGraphics

Like you can see, linking to frameworks is pretty straightforward. You just add an space and the name of the framework you are linking against. Since we want to link Twitter, everything you have to do is:

iNotitweet_FRAMEWORKS = UIKit CoreGraphics Twitter

And that’s it! You can now save the file and forget about it for the rest of the tutorial.

The final step is to implement composetTweet. For that, you have to create the TWTweetComposeViewController first and present it modally. Now this is a bit tricky and you may be asking yourself how can we present it modally if our widget is a subclass of NSObject rather than of an object that implements presentModalViewController:animated? I actually scratched my head against this problem before but I finally found the solution. The trick is to create a normal UIViewController object below the tweet composer, and set this UIViewController’s view property to your widget’s _view property. After you do that, just configure the tweet composer to dismiss when cancel is pushed and the rest of the configurations. Configuring the tweet compose view is out of the scope of this tutorial, so I will just show you the code (it should be pretty easy to understand):

-(void)composeTweet {
	TWTweetComposeViewController *twtComposer = [[TWTweetComposeViewController alloc] init];
	UIViewController *someVc = [[UIViewController alloc] init];
	twtComposer.completionHandler = ^(TWTweetComposeViewControllerResult result)
	{
		if(result == TWTweetComposeViewControllerResultCancelled)
		{
			[someVc dismissModalViewControllerAnimated:YES];
		}
	};
	someVc.view = _view;
	[someVc presentModalViewController:twtComposer animated:YES];
	[someVc release];
	[twtComposer release];
}

And that’s it! make package install it into your phone and push the button. The tweet composer will show up and you can tweet from it, or you can dismiss the window in case you change your mind.

That’s it folks! If you were/are having problems following the tutorial, I have put the full iNotitweetController.m file on my Pastebin, so feel free to download the code to compare it with yours, or to play with it in order to understand it more. Additionally, you may follow me on Twitter (@Leonnears) or leave your questions in the comments.

Oh, one more thing before I forget, to uninstall the widget, go to Cydia and look for your widget in the installed packages. You can uninstall it from there.

I will appreciate any feedback. This is the second tutorial I have ever written.