Use this API to communicate with your Lyric device and send SMS using its SIM Cards. You will be usually using 2 classes: cl.yx.YX_Session and cl.yx.YX_SMSConnector. A cl.yx.YX_Session object must be instantiated using username, password, and a cl.yx.YX_SMSConnector object, which specifies the IP address (and internally, the port) to use when connecting to the device.
If a YX_Session object has been instantiated properly - using the right credentials and the right permissions -- you can then send an SMS using one of the 3 sendMsg() methods provided.
The sendMsg() methods block until an answer is received or a timeout occurs. We also provide a queueMsg() method which does not block. See more in the next section.
Send the same message to 25 recipients, 10 seconds timeout.
public class SMSTest { public static void main(String args[]) { try { int timeout = 10; YX_Session s = new YX_Session("username", "password", new YX_SMSConnector("host")); for (int i = 0; i < 25; i++) { System.out.println( "------------------ Test " + i ); try { s.sendMsg("Hey, let's talk soon", friend_number[i], timeout, new YX_PrintNotifier()); } catch (YX_TimeoutException e1) { System.out.println( "Timeout while waiting for delivery, Aborting"); break; } catch (YX_DataException e) { System.out.println( "Protocol problem. Do we have the latest API available??"); break; } catch (YX_AuthenticationException e) { System.out.println("Authentication problem. Check user or password"); break; } catch (YX_UserPrivilegeException e) { System.out.println("User does not have enough privileges"); break; } catch (YX_ServerProblemException e) { System.out.println("Server problems"); break; } // ... } } catch (YX_IOException e) { // TODO: Connectivity problem scenario e.printStackTrace(); } } }
The above source code may be used as the base for an advertising campaign using SMS. Other examples (not shown here) may be: Send different messages to the same recipient (e.g. hourly news, stock quotes, horoscope, etc), send alarms for certain events, etc.
The Exception classes shown above extend the base class YX_Exception. If you prefer to handle all exception in one place the code could have been written like this instead:
public class SMSTest { public static void main(String args[]) { try { int timeout = 10; YX_Session s = new YX_Session("username", "password", new YX_SMSConnector("host")); for (int i = 0; i < 25; i++) { System.out.println( "------------------ Test " + i ); try { s.sendMsg("Hey, let's talk soon", friend_number[i], timeout, new YX_PrintNotifier()); } catch (YX_Exception e) { System.out.println( "Exception occurred. Aborting"); break; } // ... } } catch (YX_IOException e) { // TODO: Connectivity problem scenario e.printStackTrace(); } } }
As mentioned before, the API also provides a queueMsg() method, which is used whenever you want to send the SMS, but you do not want to block until the message is delivered. This method returns a ticket which can be used later to request information on the delivery status.
There are two ways to retrieve the delivery status: Polling for information and registering a notifier. The first example suggest a way to poll for the status, while the second one illustrates both methods. The current API version supports the first method.
Send a message and do not wait, with 30 seconds timeout.
try { String status; YX_Session s = new YX_Session("username", "password", new YX_SMSConnector("host")); // queue message, with a 30 seconds timeout try { int timeout = 30; YX_Ticket t = s.queueMsg("hi friend, see you later", "92991469", timeout); // sometime later // ... if (t != null) { status = s.requestStatus(t, 30); while(status != "done") { System.out.println("Ticket " + t + " status: " + status); status = s.requestStatus(t, 30); } } } catch (YX_TimeoutException e1) { System.out.println("Timeout while waiting for delivery, Aborting"); } catch (YX_DataException e) { System.out.println("Protocol problem. Do we have the latest API available??"); } catch (YX_AuthenticationException e) { System.out.println("Authentication problem. Check user or password"); } catch (YX_UserPrivilegeException e) { System.out.println("User does not have enough privileges"); } catch (YX_ServerProblemException e) { System.out.println("Server problems"); } } catch (YX_IOException e) { // Trying to connect to Lyric failed e.printStackTrace(); }
Send a message and do not wait, with 30 seconds timeout.
To be able to be informed when a message has been delivered (or has changed state), you should call the initNotificationServer() method first. Then you may call the requestStatus() method with the ticket that you receive to poll for information on that ticket. If you prefer not to poll but to be called back when there is a change, use the registerNotifier() method instead.
When initNotificationServer( int port ) method is called, it will open the specified IP port. The Lyric device will try to contact the API through this port. The notification process will fail if this service is not available for the Lyric to use. If you have a firewall blocking inbound connections, you may need to specify an exception for the specified IP port.
try { YX_Session s = new YX_Session("username", "password", new YX_SMSConnector("host")); int port = 9870; YX_NotificationServer ns = s.initNotificationServer(port); // you may check, at any moment, for NotificationServer's health using something like if( ns != null && ns.connectionOk() == false ) ns.restartService(); // queue message, with a 30 seconds timeout try { int timeout = 30; YX_Ticket t = s.queueMsg("hi friend, see you later", "5551234", timeout); // sometime later // ... if (t != null) { // Method 1: Poll for information (could be a loop also) System.out.println("Ticket " + t + " status: " + s.requestStatus(t)); // Method 2: Register a notifier, continue executing and let // notifier's notify( String ) method to do what you want WindowNotifier w = new WindowNotifier(); s.registerNotifier(t, w); // continue execution.. } } catch (YX_TimeoutException e1) { System.out.println("Timeout while waiting for delivery, Aborting"); } catch (YX_DataException e) { System.out.println("Protocol problem. Do we have the latest API available??"); } catch (YX_AuthenticationException e) { System.out.println("Authentication problem. Check user or password"); } catch (YX_UserPrivilegeException e) { System.out.println("User does not have enough privileges"); } catch (YX_ServerProblemException e) { System.out.println("Server problems"); } } catch (YX_IOException e) { // Trying to connect to Lyric failed e.printStackTrace(); } catch (YX_NotificationServerNotInitialized e) { // Trying to use a queueMsg related method, but with no NotificationServer? e.printStackTrace(); }
To be notified when an inbound SMS arrives, use the registerNotifier() method, with the special ticket YX_Ticket.SMSIn().
s.registerNotifier( YX_Ticket.SMSIn(), your_notifier );
1.6.3
