Module: FFI::OTR::Callbacks

Included in:
UserState
Defined in:
lib/ffi/otr/callbacks.rb

Overview

These are called from libotr, to be implemented by the application. There is already a basic implementation for #create_privkey and #write_fingerprints, so for minimal operation only #inject_message and #display_otr_message are required. To receive messages about missing callbacks, set the :debug option in your UserState.

Instance Method Summary collapse

Instance Method Details

#account_name(opdata, account, protocol) ⇒ Object

Return a newly allocated string containing a human-friendly representation for the given account.


115
116
117
# File 'lib/ffi/otr/callbacks.rb', line 115

def (opdata, , protocol)
  "#{protocol}://#{account}"
end

#account_name_free(opdata, account) ⇒ Object

Deallocate a string returned by #account_name.


120
121
122
# File 'lib/ffi/otr/callbacks.rb', line 120

def (opdata, )
  not_implemented
end

#create_instag(opdata, account, protocol) ⇒ Object

Create a instance tag for the given accountname/protocol if desired.


244
245
246
247
248
249
250
251
# File 'lib/ffi/otr/callbacks.rb', line 244

def create_instag(opdata, , protocol)
  if @opts[:instags]
    debug "Creating new instance tag for #{account},#{protocol}"
    otrl_instag_generate(@userstate, @opts[:instags], , protocol)
  else
    not_implemented
  end
end

#create_privkey(opdata, account, protocol) ⇒ Object

Create a private key for the given accountname/protocol if desired.


15
16
17
18
19
20
21
22
23
# File 'lib/ffi/otr/callbacks.rb', line 15

def create_privkey(opdata, , protocol)
  if @opts[:privkey]
    debug "Generating private key for #{account} (#{protocol}). This may take a while."
    privkey_generate(@opts[:privkey], @account, @protocol)
    debug "Private key generated. Fingerprint is #{fingerprint}."
  else
    not_implemented
  end
end

#display_otr_message(opdata, account, protocol, user, msg) ⇒ Object

OTR control message for a particular accountname / protocol / username conversation. Return 0 if you are able to successfully display it. If you return non-0 (or if this function is NULL), the control message will be displayed inline, as a received message, or else by using the above notify() callback.


51
52
53
54
# File 'lib/ffi/otr/callbacks.rb', line 51

def display_otr_message(opdata, , protocol, user, msg)
  not_implemented
  0
end

#gone_insecure(opdata, context) ⇒ Object

A ConnContext has left a secure state.


93
94
95
# File 'lib/ffi/otr/callbacks.rb', line 93

def gone_insecure(opdata, context)
  not_implemented
end

#gone_secure(opdata, context) ⇒ Object

A ConnContext has entered a secure state


88
89
90
# File 'lib/ffi/otr/callbacks.rb', line 88

def gone_secure(opdata, context)
  not_implemented
end

#handle_msg_event(opdata, msg_event, context, message, err) ⇒ Object

Handle and send the appropriate message(s) to the sender/recipient depending on the message events. All the events only require an opdata, the event, and the context. The message and err will be NULL except for some events (see below). The possible events are:


239
240
241
# File 'lib/ffi/otr/callbacks.rb', line 239

def handle_msg_event(opdata, msg_event, context, message, err)
  not_implemented
end

#handle_smp_event(opdata, smp_event, context, progress_percent, question) ⇒ Object

Update the authentication UI with respect to SMP events These are the possible events:


194
195
196
# File 'lib/ffi/otr/callbacks.rb', line 194

def handle_smp_event(opdata, smp_event, context, progress_percent, question)
  not_implemented
end

#inject_message(opdata, account, protocol, recipient, message) ⇒ Object

Send the given IM to the given recipient from the given account/protocol.


35
36
37
# File 'lib/ffi/otr/callbacks.rb', line 35

def inject_message(opdata, , protocol, recipient, message)
  not_implemented
end

#is_logged_in(opdata, account, protocol, recipient) ⇒ Object

Report whether you think the given user is online. Return 1 if you think he is, 0 if you think he isn't, -1 if you're not sure. If you return 1, messages such as heartbeats or other notifications may be sent to the user, which could result in "not logged in" errors if you're wrong.


30
31
32
# File 'lib/ffi/otr/callbacks.rb', line 30

def is_logged_in(opdata, , protocol, recipient)
  not_implemented
end

#log_message(opdata, message) ⇒ Object

Log a message. The passed message will end in "\n".


104
105
106
# File 'lib/ffi/otr/callbacks.rb', line 104

def log_message(opdata, message)
  debug message[0...-1]
end

#max_message_size(opdata, context) ⇒ Object

Find the maximum message size supported by this protocol.


109
110
111
# File 'lib/ffi/otr/callbacks.rb', line 109

def max_message_size(opdata, context)
  @opts[:max_message_size]
end

#new_fingerprint(opdata, userstate, account, protocol, from, fingerprint) ⇒ Object

A new fingerprint for the given user has been received.


74
75
76
# File 'lib/ffi/otr/callbacks.rb', line 74

def new_fingerprint(opdata, userstate, , protocol, from, fingerprint)
  not_implemented
end

#notify(opdata, level, account, protocol, user, title, primary, secondary) ⇒ Object

Display a notification message for a particular accountname / protocol / username conversation.


41
42
43
# File 'lib/ffi/otr/callbacks.rb', line 41

def notify(opdata, level, , protocol, user, title, primary, secondary)
  not_implemented
end

#otr_error_message(opdata, context, err_code) ⇒ Object

Return a string according to the error event. This string will then be concatenated to an OTR header to produce an OTR protocol error message. The following are the possible error events:


149
150
151
# File 'lib/ffi/otr/callbacks.rb', line 149

def otr_error_message(opdata, context, err_code)
  not_implemented
end

#otr_error_message_free(opdata, message) ⇒ Object

Deallocate a string returned by otr_error_message


154
155
156
# File 'lib/ffi/otr/callbacks.rb', line 154

def otr_error_message_free(opdata, message)
  not_implemented
end

#policy(opdata, context) ⇒ Object

Return the OTR policy for the given context.


10
11
12
# File 'lib/ffi/otr/callbacks.rb', line 10

def policy(opdata, context)
  @opts[:policy]
end

#protocol_name(opdata, protocol) ⇒ Object

Return a newly allocated string containing a human-friendly name for the given protocol id


64
65
66
# File 'lib/ffi/otr/callbacks.rb', line 64

def protocol_name(opdata, protocol)
  not_implemented
end

#protocol_name_free(opdata, protocol_name) ⇒ Object

Deallocate a string allocated by protocol_name


69
70
71
# File 'lib/ffi/otr/callbacks.rb', line 69

def protocol_name_free(opdata, protocol_name)
  not_implemented
end

#received_symkey(opdata, context, use, usedata, usedatalen, symkey) ⇒ Object

We received a request from the buddy to use the current "extra" symmetric key. The key will be passed in symkey, of length OTRL_EXTRAKEY_BYTES. The requested use, as well as use-specific data will be passed so that the applications can communicate other information (some id for the data transfer, for example).

This is called when a remote buddy has specified a use for the current symmetric key. If your application does not use the extra symmetric key it does not need to provide an implementation for this operation.


133
134
135
# File 'lib/ffi/otr/callbacks.rb', line 133

def received_symkey(opdata, context, use, usedata, usedatalen, symkey)
  not_implemented
end

#resent_msg_prefix(opdata, context) ⇒ Object

Return a string that will be prefixed to any resent message. If this function is not provided by the application then the default prefix, "[resent]", will be used.

These operations give the option of chosing an alternative to the English string "[resent]", when a message is resent.


164
165
166
# File 'lib/ffi/otr/callbacks.rb', line 164

def resent_msg_prefix(opdata, context)
  not_implemented
end

#resent_msg_prefix_free(opdata, prefix) ⇒ Object

Deallocate a string returned by resent_msg_prefix


169
170
171
# File 'lib/ffi/otr/callbacks.rb', line 169

def resent_msg_prefix_free(opdata, prefix)
  not_implemented
end

#still_secure(opdata, context, is_reply, _) ⇒ Object

We have completed an authentication, using the D-H keys we already knew. is_reply indicates whether we initiated the AKE.


99
100
101
# File 'lib/ffi/otr/callbacks.rb', line 99

def still_secure(opdata, context, is_reply, _)
  not_implemented
end

#update_context_list(opdata) ⇒ Object

When the list of ConnContexts changes (including a change in state), this is called so the UI can be updated


58
59
60
# File 'lib/ffi/otr/callbacks.rb', line 58

def update_context_list(opdata)
  not_implemented
end

#write_fingerprints(opdata) ⇒ Object

The list of known fingerprints has changed. Write them to disk.


79
80
81
82
83
84
85
# File 'lib/ffi/otr/callbacks.rb', line 79

def write_fingerprints(opdata)
  if @opts[:fingerprints]
    privkey_write_fingerprints(@opts[:fingerprints])
  else
    not_implemented
  end
end