Context Navigation

Introduction

Hi thanks fro reading more about the Mixip module that helps you write applications that use the MXIT protocol. The first prerequisite for using this library is probable that you should have some kind of knowledge about the Perl language. We are not going to teach you the language so if you don't know what Perl is ask Google it is not that difficult to learn.

The second thing you need is to install the module. There are various ways such as installing using make or just including the Mixip.pm file with your application read more on this in the Install part of the wiki.

So when all is said and done you will be able to start your Perl application like this:

#!/usr/bin/perl

use Mixip::Main; #Use the Mixip lib

#Create a new Mixip::Main object
$mxit = Main->new();

$mixit->Use the module functions

...

When writing your application and using Mixip there are basically three things you can use:

Subroutines to set values also called value subroutines
Subroutines to notify you of certain events also called callback subroutines
Subroutines that perform certain functions also called functional subroutines

Details

Notes

A few notes that did not fit anywhere else.

Offline messages

Offline messages gets sent with the contact status updates after login. You can acces the messages from the contact_status_change callback but this is messy. So each offline message gets sent to message_received callback and is treated as a normal message. Please note that the message_received callback will happen for each message before the contact_status_change callback is executed.

Unresolved contact invites

Works in the same way as Offline messages exept that any unresolved contacts is sent with the contact list.

Main.pm

use Mixip::Main;

You can think of Main as the encapsulating package that bind the library together.

Just using main should be enough for most applications but you can also access the other packages using the Value Subroutines provided by Main.

A good example is login() that encrypts the password before sending. Main calls Encrypt.pm and does the encryption for you. If for some reason you need to access Encrypt.pm you can use the Value Subroutine that returns the Encrypt module or use Mixip::Encrypt in your application.

Paramaters: None at this time

Value Subroutines

You can call these subroutines to set or get certain values. When the subroutine is not passed a value the current value is returned. Example: To set the pin that the connection must use to 1234:

#!/usr/bin/perl

use Mixip::Main; #Use the Mixip lib

#Create a new Mixip::Main object
$mxit = Main->new();

$mxit->pin("1234"); 

#Print the current pin
print $mxit->pin;

#Output will be 1234

debug

Turns on some extra debug information.

Params: 1 or 0

Type: Int

number

Set the number that the connection must use. Must be in correct format 27 etc. (Not 083 but 2783)

Params: The number to use

Type: String

Set the pin number that the connection must use.

Params: The pin to use

Type: String

cid

Set the CID the connection should use. See also *get_jad_cid* that reads .jad for CID

Params: The CID to use

Type: String

apname

Set a name for your application may be useful later but not used currently

Params: The application name to use to use Type: String

port

Set the port that must be used when connecting to the MXIT server. If not set the default will be used.

Params: The Port to use

Type: Number

Default: 9119

server_ip

Set the host name for the MXIT server that we are connecting to. If not set the default will be used. It says server_ip but it is actually the host name.

Params: The host name to use

Type: String

Default: stream.mxit.co.za

encrypt

Get or set the Encrypt.pm package.

Note encrypt will be undef until:

login() is called
The PIN and CID gets passed to the function as paramaters
An Encrypt.pm object gets passed to this function as parameter.

Params: None or (Pin,CID) or Encrypt object

Type: Encrypt.pm

Default: undef until login() is called

Callback Subroutines

You can use callback routines when you want to be notified of certain events by the module. You will associate your subroutine with one of the defined callbacks. When that callback happens your subroutine will be executed and passed certain values that is needed for your subroutine to make sense. To connect your subroutine with a callback use the add_handler('callback',\&your_sub). Example:

#Create a new Mixip::Main object
$mxit = Main->new();

#Add a callback when a raw line is received from server:
$mxit->add_handler('raw_line',\&new_raw_line);  
#Add the rest of them 
#...

#Don't forget your subs for each callback 
sub new_raw_line
{
#First get our raw line
my $line = @_[1];

#Give the user a nice message
print "RAW SERV: $line";
}

raw_line

When a raw line was received from the server this gets called. The line gets passed on without being changed.

_Returns:_

@_[0] = Reference to the current code block.

@_[1] = String containing the raw line.

end_read

When the socket stopped reading from the server. Basically the connection now ended.

_Returns:_

@_[0] = Reference to the current code block (Check this please).

connecting

The connection is being established.

_Returns:_

@_[0] = Reference to the current code block (Check this please).

start_read

The connection started to read from the server.

_Returns:_

@_[0] = Reference to the current code block (Check this please).

connected

We are now connected to the server.

_Returns:_

@_[0] = Reference to the current code block (Check this please).

connect_fail

The server failed to connect.

_Returns:_

@_[0] = Reference to the current code block

@_[1] = The Socket that failed.

raw_send

Gets called if the user sends a raw message to the server using ?

_Returns:_

@_[0] = Reference to the current code block

login_send

Gets called if the the user does login with login()

_Returns:_

@_[0] = Reference to the current code block

contacts_received

A list of contacts was received after login

_Returns:_

@_[0] = Reference to the current code block

@_[1] = The original unmodified packet

@_[2] = The original packet modified to replace null bytes

@_[3] = An array reference containing arrays representing each contact

@_[4] = An array reference containing hashes representing each contact

@_[5] = An array reference containing each of the contact invites not accepted/rejected/blocked since invite received. (Each one is also handled as a invite received see contact_invite_received)

_Example:_

#Create a new Mixip::Main object
$mxit = Main->new();

#New list of contacts recived
$mxit->add_handler('contacts_received',\&contacts_received); 

#Connect and Login
#...

sub contacts_received
{
print "Contact list recieved\n"; 

print "Argument 0: @_[0]\n\n";
print "Argument 1: @_[1]\n\n"; 
print "Argument 2: @_[2]\n\n"; 
print "Argument 3: @_[3]\n\n"; 
print "Argument 4: @_[4]\n\n"; 

#Check if any invites outstanding
# (Each one is also handled as a invite received see contact_invite_received)

print "You have the following invites that you did not accept/reject/block";

my $con_out = @_[5];

for $con (@$con_out)
{
print "$con\n";
}

my $name = @_[3]; #Argument 3 the contacts 

#Print each contacts details using argument 3
for my $contacts (@$name){
 print "\nThis is one array of contact information: $contacts\n";
	for my $contact_info (@$contacts)
	{
	print "$contact_info \n";
	}
 }

#Another way to print each contacts details using argument 3
for (my $i=0; $i < @$name; $i++) {
 print "\n";
	for(my $b=0; $b < @$name; $b++)
	{
	print "$name->[$i][$b]\n";
   }
  }


#Using argument 4 the Hash
my $name_h = @_[4]; #Argument 4 the hash contacts 

for $contact_h (@$name_h )
 {
	print "\nThis is a Hash of contact information: $contact_h\n";
	while ( my ($key, $value) = each(%$contact_h) ) {
        print "$key => $value\n";
    }
 }
 
#You have contacts print just the nick name of each.
print "Contact list recieved\n";
print "You have the following contacts:\n";

my $name_h = @_[4]; #Argument 4 the hash contacts 

for $contact_h (@$name_h )
{
	 print "%$contact_h->{ 'nick' }\n"; 
} 
}

contact_status_change

When a contact changes status.

@_[0] = Reference to the current code block

@_[1] = The original unmodified packet

@_[2] = The original packet modified to replace null bytes

@_[3] = An array reference containing arrays representing each contact that changed

@_[4] = An array reference containing hashes representing each contact that changed

@_[5] = An array containing all the messages that was sent to the user while ofline

When you login only the online users will send their status if the user is ofline he will not show in the list

When using the hash the key 'num1' will indicate what the new Status is, Whe using the array look at [3]:

0 = Offline

1 = Online

2 = Away

4= Busy

When using the hash the key 'num3' will indicate what the new Mood status is, Whe using the array look at [5]:

0 = None

1 = Angry

2 = Excited

3 = Grumpy

4 = Happy

5 = In love

6 = Invincible

7 = Sad

8 = Hot

9 = Sick

10 = Sleepy

_Example:_

#Almost the same as contacts_received only new thing is @_[5] containing stored messages

#Show ofline messages
my @ofline_mes = @_[5];

for my $ofmes (@ofline_mes)
{
  for my $ofmes_info (@$ofmes)
        {
        print "$ofmes_info \n";
        }

}

my $name_h = @_[4]; #Argument 4 the hash contacts that changed 

for $contact_h (@$name_h )
{   
	#Tell user if Status changed
	if(%$contact_h->{'num1'} eq 0)
	{
	print "$contact_h->{ 'nick' } is now offline\n";
	}
	
	if(%$contact_h->{'num1'} eq 1)
	{
	print "$contact_h->{ 'nick' } is now online\n";
	}
	
	if(%$contact_h->{'num1'} eq 2)
	{
	print "$contact_h->{ 'nick' } is now away\n";
	}
	
	if(%$contact_h->{'num1'} eq 4)
	{
	print "$contact_h->{ 'nick' } is now busy\n";
	}
	
	#Tell user if Mood changed
	if(%$contact_h->{'num3'} eq 4)
	{
	print "$contact_h->{ 'nick' } is now Happy :) \n";
	}
	
	if(%$contact_h->{'num3'} eq 1)
	{
	print "$contact_h->{ 'nick' } is now Angry (T_T) \n";
	}
	
	if(%$contact_h->{'num3'} eq 9)
	{
	print "$contact_h->{ 'nick' } is now Sick :-~) \n";
	}
	#You get my drift...
}

message_received

A new message was received by us.

@_[0] = Reference to the current code block

@_[1] = The original unmodified packet

@_[2] = The original packet modified to replace null bytes

@_[3] = An array refernce containing the message

@_[4] = A hash reference containing the message with keys: 'num1','num2','host','num3','num4','num5', 'num6','message'

@_[5] = A string containing the senders host

@_[6] = A string containing the message

_Example:_

#Display the new message to user
my $host_name = @_[5]; 
my $mes = @_[6];

#A message only sends the host name so get the nick so we can know from who the message is:
my $nick = $mxit->get_nick($host_name);

print "$nick [$host_name] : $mes\n";

contact_invite_received

A new contact invite was received.

This will also executed if any invites exist that gets sent with the rest of the contacts.

@_[0] = Reference to the current code block

@_[1] = The original unmodified packet

@_[2] = The original packet modified to replace null bytes

@_[3] = An array refernce containing the invite details

@_[4] = A hash reference containing the invite details with keys: 'num1','num2','host','nick','mes'

_Example_

$mxit->add_handler('contact_invite_received',\&contact_invite_handler); #We recived a contact invite I hope it is koos

sub contact_invite_handler
{
my $invite = @_[4]; #Argument 4 the hash 
print "Invite received from $invite->{'nick'} ($invite->{'host'}) ($invite->{'mes'})\n";
}

Functional Subroutines

These are the subroutines that you can use to communicate with the MXit server or tp preform certain other functions. They are called the same way as the value subs.

connect

Creates a new connection to the MXit server.

Params: Nothing

Returns: Nothing

_Example:_

use Mixip::Main; #Use the Mixip lib

#Create a new Mixip::Main object
$mxit = Main->new();

#Setup the user details
$mxit->number("27123456789"); #Make sure about the 27
$mxit->pin("123456");
$mxit->cid("E70B7B3E-A673-4A04-9A52-5FF6DECFFF39"); #Get from .jad

#Setup callbacks 
...

#Do connect
$mxit->connect; #Or  $mxit->connect()

#Do login
$mxit->login;

Logs in using the account details and encrypts the password. Crypt::Rijndael and MIME::Base64 needs to be in @include.

Params: Nothing

Returns: Nothing

_Example:_

See the connect() example

login_old

Login without using encryption. This is not recommended since the MXIT version will be bumped down to 5.1.1 and certain features might not work. Only use this if you have a problem and think it might be encryption related.

logout

Logs out.

Params: Nothing

Returns: Nothing

disconnect

Close the connection to the server.

Params: Nothing

Returns: Nothing

send_raw

Sends a raw line to the server. This line will be sent directly over the connection without being modified.

Params: The raw line you want to send to the server (String)

Returns: Nothing

get_jad_cid

Whe provided with a path to a .jad file this function will return a CID

Params: The full path to the .jad file (String)

Returns: String containing the CID that was in the .jad file

get_nick

When the contacts are sent after login by the MXIT server Mixip makes a note what host belong to what nick. Using this function you can send a host name and get back the nickname

Params: The host name (27834151622@…) (String)

Returns: String containing the nick name

_Example:_

See example from callback message_received that uses the function

get_host

This is just the reverse of get_nick. Mixip also keeps track of each host and here you provide the nick and the host gets returned.

Params: The nick name (String)

Returns: String containing the host name

send_message

Sends a message to the nick given as the first param. The message is given as the second param.

Params: The nick name (String), The message (String)

Returns: Nothing

delete_contact

Delete the contact thats nick was givin as the only argument

Params: The nick name to delete (String)

Returns: Nothing

invite_contact

Invite a contact takes two paramaters first the number of the person and then the nickname

Params: The number must be in 27 format (String), The nick that belongs to the number in first argument (String)

Returns: Nothing

reject_contact_inv

Rejects a contact invitation. Takes on paramater the nickname of the contact invitation to reject.

Params: The nick name to reject (String)

Returns: Nothing

accept_contact_inv

Accept a contact invitation. Takes on paramater the nickname of the contact invitation to accept.

Params: The nick name to accept (String)

Returns: Nothing

Encrypt.pm

use Mixip::Encrypt;

Called by Main.pm to encrypt the users password.

Accessed through Main.pm with value subroutine encrypt. Or directly using Mixip::Encrypt

Parameters: 'Pin'=>"Pin number" , 'Cid'=>"CID number"

Value Subroutines

You can call these subroutines to set or get certain values. When the subroutine is not passed a value the current value is returned.

Set the pin number that must be encrypted.

Params: The pin to be encrypted

Type: String

cid

Set the CID that will be used for the key to encrypt the pin

Params: The CID to use

Type: String

Functional Subroutines

These are the subroutines that you can use to preform certain functions. They are called the same way as the value subs.

enc_pin

Encrypts a pin with CID as key

Params: Nothing

Returns: Encrypted key

Download in other formats:

Plain Text